Sam's Blog

Installing Free IPA in Docker

Samuel Hulme — Fri, 15 Dec 2023 00:00:00 GMT

Prerequisites

The following applications need to be installed on your system:

Docker
Git

The guide will assume some details:

Hostname: ipa.minersonline.lan
Storage path: /DATA/AppData/freeipa-server
Server IP: 10.0.0.97

You may changes these assumptions based on your requirements. The Hostname will determine the domain name of the Free IPA setup, in this example minersonline.local. The Storage path will determine where Free IPA will store its data.

I'm running these commands on an Ubuntu 22.04 system. The commands are probably the same on your system.

1. Setup hostname

sudo hostnamectl set-hostname ipa.minersonline.lan

sudo nano /etc/hosts

Add the line 10.0.0.97 ipa.minersonline.lan ipa to the top of the file but change 10.0.0.97 to your machine's IP

Press Control + X then Y to save the file.

2. Configure your DNS

On your router or your DNS server (like PiHole) add the ipa.minersonline.lan hostname to match the IP of your machine.

:::note This step is different for different models of routers or DNS servers, please consult their documentation. :::

Steps

1. Choose a container

Chose a container from the [Free IPA Docker Hub](https://hub.docker.com/r/Free IPA/freeipa-server/tags). I've chosen fedora-rawhide.

2. Perform the installation

The following command will run the image we built in the last step. This will run the installation process.

I recommend answering no to Do you want to configure integrated DNS (BIND)? because the BIND dns server caused problems during my installation.

docker run --name freeipa-server -ti \
   --read-only \
   -h ipa.minersonline.lan -p 53:53/udp -p 53:53 -p 80:80 -p 443:443 -p 389:389 -p 636:636 -p 88:88 -p 464:464 -p 88:88/udp -p 464:464/udp -p 123:123/udp \
   --sysctl net.ipv6.conf.all.disable_ipv6=0 \
   -v /sys/fs/cgroup/freeipa.scope:/sys/fs/cgroup:ro \
   -v /DATA/AppData/freeipa-server:/data:Z \
   --tmpfs /run --tmpfs /tmp freeipa/freeipa-server:fedora-rawhide

If you get any errors please see the errors section for your error. {: .prompt-tip }

3. Delete the existing container

docker stop freeipa-server
docker rm freeipa-server

4. Restart the container

docker run -d --name freeipa-server -ti \
   --read-only \
   -h ipa.minersonline.lan -p 53:53/udp -p 53:53 -p 80:80 -p 443:443 -p 389:389 -p 636:636 -p 88:88 -p 464:464 -p 88:88/udp -p 464:464/udp -p 123:123/udp \
   --sysctl net.ipv6.conf.all.disable_ipv6=0 \
   -v /sys/fs/cgroup/freeipa.scope:/sys/fs/cgroup:ro \
   -v /DATA/AppData/freeipa-server:/data:Z \
   --restart unless-stopped \
   --tmpfs /run --tmpfs /tmp freeipa/freeipa-server:fedora-rawhide

:::tip If you get any errors please see the errors section for your error. :::

Errors

`Failed to create /init.scope control group: Read-only file system`

If you get the error:

Failed to create /init.scope control group: Read-only file system
Failed to allocate manager object: Read-only file system
[!!!!!!] Failed to allocate manager object.
Exiting PID 1...

1. Delete existing containers / data

docker rm freeipa-server and rm -rf /DATA/AppData/freeipa-server

2. Perform the installation again

docker run --name freeipa-server -ti \
   --read-only \
   -h ipa.minersonline.lan -p 53:53/udp -p 53:53 -p 80:80 -p 443:443 -p 389:389 -p 636:636 -p 88:88 -p 464:464 -p 88:88/udp -p 464:464/udp -p 123:123/udp \
   --sysctl net.ipv6.conf.all.disable_ipv6=0 \
   --cgroupns host \
   --security-opt seccomp=unconfined \
   -v /sys/fs/cgroup/freeipa.scope:/sys/fs/cgroup:rw \
   -v /DATA/AppData/freeipa-server:/data:Z \
   --privileged \
   --tmpfs /run --tmpfs /tmp freeipa/freeipa-server:fedora-rawhide --no-ntp

3. Delete the new container

docker stop freeipa-server
docker rm freeipa-server

4. Restart the container again

docker run -d --name freeipa-server -ti \
   --read-only \
   -h ipa.minersonline.lan -p 53:53/udp -p 53:53 -p 80:80 -p 443:443 -p 389:389 -p 636:636 -p 88:88 -p 464:464 -p 88:88/udp -p 464:464/udp -p 123:123/udp \
   --sysctl net.ipv6.conf.all.disable_ipv6=0 \
   --cgroupns host \
   --security-opt seccomp=unconfined \
   -v /sys/fs/cgroup/freeipa.scope:/sys/fs/cgroup:rw \
   -v /DATA/AppData/freeipa-server:/data:Z \
   --restart unless-stopped \
   --privileged \
   --tmpfs /run --tmpfs /tmp freeipa/freeipa-server:fedora-rawhide --no-ntp

Configuring Next Cloud to Use Free IPA

Samuel Hulme — Sat, 16 Dec 2023 00:00:00 GMT

Prerequisites

The following applications need to be installed on your system

Next Cloud
Free IPA.

The guide will assume some details:

Free IPA server hostname: ipa.minersonline.lan
Free IPA realm domain: mineronline.lan

You may changes these assumptions based on your requirements.

Steps

1. Step up a System User Account

The System User Account is a dedicated account that the Next Cloud instance will use to get user information from your Free IPA server.

1. Login into the Free IPA web interface

Open up your browser and navigate to https://ipa.minersonline.lan. Accept the security warning.

If not logged in, enter your admin account details. By default, the user name is admin and the password is the one you gave during the Free IPA installation.

2. Add the user

On the "Users" page click the "Add" button.
Set the "User login" to something explanatory, for example: NextCloudsystemuser.
The "First Name" and "Last Name" can be set to whatever you want, for example Next Cloud.
Set the password to something secure and note it down.

3. Make the user an "admin"

The new user needs to be an admin so it can be used to receive information about all users.

Click on the NextCloudsystemuser user on the "Active Users" page.
Open the "User Groups" tab.
Click on the "Add" button.
Click the checkbox next to "admins".
In the middle of the dialog press the button pointing to the right ">".
Finally, press "Add".

2. Configure Next Cloud LDAP / AD Integration

1. Enable / Install the "LDAP user and group backend" app

The "LDAP user and group backend" app is used to provide LDAP support for Next Cloud.

Go to the Next Cloud apps page and enable the "LDAP user and group backend" app. Optionally, I recommend installing the "Write support for LDAP" and the "LDAP Contacts Backend" app.

2. Configure LDAP / AD connection settings

Open the "Administration Settings" page and go to the "LDAP / AD integration" page.
In the "Host" field enter your Free IPA server's hostname, for example: ipa.minersonline.lan. If your running your Next Cloud in Docker then you may need to use the server's IP address instead.
Set the "Port" field to 389.
Set the "User DN" to uid=NextCloudsystemuser,cn=users,cn=accounts,dc=minersonline,dc=lan

The NextCloudsystemuser part is the "User Login" we set earlier.

The dc=minersonline,dc=lan part depends on your Free IPA realm domain. For example if your domain is office.example.com then you would use dc=office,dc=example,dc=com. {: .prompt-tip }
Set the "Password" to what you noted down earlier.
Then press "Save Credentials".
Set the "One Base DN per line" to dc=minersonline,dc=lan

Again, The dc=minersonline,dc=lan part depends on your Free IPA realm domain. For example if your domain is office.example.com then you would use dc=office,dc=example,dc=com. {: .prompt-tip }
Finally, press "Continue".

3. Configure LDAP Groups

On the same page click on the "Groups" tab.
Click the "Edit LDAP Query" link.
In the "Edit LDAP Query" text box type: (|(cn=ipausers)). This filter will add the ipausers group from the Identity > Groups page on the Free IPA interface.

4. Configure LDAP Login Attributes

On the same page click on the "Login Attributes" tab.
Click the "Edit LDAP Query" link.
In the "Edit LDAP Query" text box type: (&(objectclass=*)(uid=%uid)).
Finally, press "Continue".

5. Configure Advanced Settings

On the same page click on the "Advanced" tab.
Open up the "Directory Settings" section.
Inside the "Base User Tree" type cn=users,cn=accounts,dc=minersonline,dc=lan.

Again, The dc=minersonline,dc=lan part depends on your Free IPA realm domain. For example if your domain is office.example.com then you would use dc=office,dc=example,dc=com. {: .prompt-tip }
Inside the "Base Group Tree" type cn=groups,cn=accounts,dc=minersonline,dc=lan.

Again, The dc=minersonline,dc=lan part depends on your Free IPA realm domain. For example if your domain is office.example.com then you would use dc=office,dc=example,dc=com. {: .prompt-tip }
Set the "Group-Member association" to member.
Open up the "Special Attributes" section.
Make sure the "Email Field" is set to mail.
Set the "User Home Folder Naming Rule" to cn.
Finally press "Test Configuration". If all settings are good then a "Valid configuration, connection established!" message should be displayed.

Configuring Next Cloud to Use Samba

Samuel Hulme — Thu, 21 Dec 2023 00:00:00 GMT

Prerequisites

The following applications need to be installed on your system

Next Cloud
A Samba domain controller.

The guide will assume some details:

Hostname: ipa.minersonline.lan
Storage path: /DATA/AppData/freeipa-server
Server IP: 10.0.0.97

You may changes these assumptions based on your requirements.

Steps

1. Step up a System User Account

The System User Account is a dedicated account that the Next Cloud instance will use to get user information from your Sa,ba server. Call the user NextCloudsystemuser, and set a secure password and note it down.

If you have Windows clients connected to the domain then you can use the "Active Directory Users and Computers" program to add the user.

If not, you may need use the Samba command line tools.

2. Allow Next Cloud to accept any LDAP certificate

1. Connect to your Next Cloud server's console

This depends on how you have installed Next Cloud. For me:

sudo docker exec -it nextcloud bash

2. Edit LDAP configuration

Open the file /etc/ldap/ldap.conf and add the line to the bottom:

TLS_REQCERT never

3. Restart Next Cloud

You may need to restart your Next Cloud server. For me:

sudo docker restart nextcloud

3. Configure Next Cloud LDAP / AD Integration

1. Enable / Install the "LDAP user and group backend" app

The "LDAP user and group backend" app is used to provide LDAP support for Next Cloud.

Go to the Next Cloud apps page and enable the "LDAP user and group backend" app. Optionally, I recommend installing the "Write support for LDAP" and the " LDAP Contacts Backend" app.

2. Configure LDAP / AD connection settings

Open the "Administration Settings" page and go to the "LDAP / AD integration" page.
In the "Host" field enter your Samba server's hostname, for example: ldaps://ipa.minersonline.lan. If your running your Next Cloud in Docker then you may need to use the server's IP address instead.
Set the "Port" field to 636.
Set the "User DN" to cn=NextCloudsystemuser,cn=users,dc=minersonline,dc=lan

The NextCloudsystemuser part is the user account we set earlier.

The dc=minersonline,dc=lan part depends on your Samba realm domain. For example if your domain is office.example.com then you would use dc=office,dc=example,dc=com. {: .prompt-tip }
Set the "Password" to what you noted down earlier.
Then press "Save Credentials".
Set the "One Base DN per line" to dc=minersonline,dc=lan

Again, The dc=minersonline,dc=lan part depends on your Samba realm domain. For example if your domain is office.example.com then you would use dc=office,dc=example,dc=com. {: .prompt-tip }
Finally, press "Continue".

3. Configure LDAP Groups

On the same page click on the "Groups" tab.
Click the "Edit LDAP Query" link.
In the "Edit LDAP Query" text box type: (&(objectclass=group)). This filter will add all Samba groups (even the default builtin ones).

4. Configure LDAP Login Attributes

On the same page click on the "Login Attributes" tab.
Click the "Edit LDAP Query" link.
In the "Edit LDAP Query" text box type: (&(objectclass=person)).
Finally, press "Continue".

5. Configure Advanced Settings

On the same page click on the "Advanced" tab.
Open up the "Directory Settings" section.
Inside the "User Display Name" type displayName.
Inside the "Base User Tree" type cn=users,dc=minersonline,dc=lan.

Again, The dc=minersonline,dc=lan part depends on your Samba realm domain. For example if your domain is office.example.com then you would use dc=office,dc=example,dc=com. {: .prompt-tip }
Inside the "Base Group Tree" type cn=users,dc=minersonline,dc=lan

Again, The dc=minersonline,dc=lan part depends on your Samba realm domain. For example if your domain is office.example.com then you would use dc=office,dc=example,dc=com. {: .prompt-tip }
Set the "Group-Member association" to member (AD).
Open up the "Special Attributes" section.
Set the "User Home Folder Naming Rule" to cn.
Finally press "Test Configuration". If all settings are good then a "Valid configuration, connection established!" message should be displayed.

Installing Samba on Ubuntu

Samuel Hulme — Thu, 21 Dec 2023 00:00:00 GMT

Prerequisites

This guide recommends using Ubuntu 22.04 or later.

The guide will assume some details:

Server IP: 10.0.0.97
Kerberos Realm: MINERSONLINE.LAN
Kerberos server hostname: ipa.minersonline.lan
Kerberos administrative server hostname: ipa.minersonline.lan

You may changes these assumptions based on your requirements.

1. Setup hostname

Set the hostname.

sudo hostnamectl set-hostname ipa.minersonline.lan

Add the hostname to hosts file.

sudo nano /etc/hosts

Add the line 10.0.0.97 ipa.minersonline.lan ipa to the top of the file but change 10.0.0.97 to your machine's IP

Press Control + X then Y to save the file.

2. Install dependencies

sudo apt-get install samba krb5-user krb5-config winbind libpam-winbind libnss-winbind

During installation you may get asked for your Kerberos Realm, Kerberos server hostname, and Kerberos administrative server hostname.

3. Provision Samba

1. Stop existing Samba services

sudo systemctl stop samba-ad-dc.service smbd.service nmbd.service winbind.service
sudo systemctl disable samba-ad-dc.service smbd.service nmbd.service winbind.service

2. Backup Samba configuration

sudo mv /etc/samba/smb.conf /etc/samba/smb.conf.initial

3. Reconfigure Samba

sudo samba-tool domain provision --use-rfc2307 --interactive

You will get asked for the following information:

Realm: MINERSONLINE.LAN.
Domain: MINERSONLINE.
Server Role: dc.
DNS backend: SAMBA_INTERNAL.
DNS forwarder IP address: Your DNS server's IP (normally your gateway) or Cloudflare (1.1.1.1) or Google (8.8.8.8).
Administrator password: Enter something secure and rememberable.

4. Make a link to use Samba's Kerberos configuration

sudo mv /etc/krb5.conf /etc/krb5.conf.initial
sudo ln -s /var/lib/samba/private/krb5.conf /etc/

4. Start Samba

sudo samba

2. Configure local DNS

DNS is used so external services can locate the domain controller and query the services located on it. This will allow clients to connect to the domain controller easily.

1. Install resolvconf

sudo apt install resolvconf
sudo systemctl enable --now resolvconf.service

2. Configure resolvconf

sudo nano /etc/resolvconf/resolv.conf.d/head

Add nameserver 127.0.01 at the bottom. Press Control + X then Y to save the file. We use 127.0.0.1 because Samba is acting as the DNS server and they are forwarding external DNS requests to outside world.

3. Delete conflicting DNS records

Doing the command:

samba-tool dns query 10.0.0.97 minersonline.lan minersonline.lan A

will allow you to check if you have conflicting DNS records. If the IPs 172.17.0.1, 172.19.0.1, and 172.18.0.1 appear above the server's ipa 10.0.0.97. These conflicting records will confuse clients because they will try to connect to themselves instead of the domain controller.

samba-tool dns delete 10.0.0.97 minersonline.lan minersonline.lan A 172.17.0.1
samba-tool dns delete 10.0.0.97 minersonline.lan minersonline.lan A 172.19.0.1
samba-tool dns delete 10.0.0.97 minersonline.lan minersonline.lan A 172.18.0.1

samba-tool dns delete 10.0.0.97 minersonline.lan ipa.minersonline.lan A 172.17.0.1
samba-tool dns delete 10.0.0.97 minersonline.lan ipa.minersonline.lan A 172.19.0.1
samba-tool dns delete 10.0.0.97 minersonline.lan ipa.minersonline.lan A 172.18.0.1

4. Running Samba on startup

Running Samba on system startup is a good idea if you want clients to be allowed to connect automatically. To do this run the following command:

sudo update-rc.d smbd defaults

5. Testing / verification

1. Verify DNS is working

host -t SRV _kerberos._udp.minersonline.lan

You should get a message like:

_kerberos._udp.minersonline.lan has SRV record 0 100 88 ipa.minersonline.lan.

2. Test Kerberos

kinit administrator@MINERSONLINE.LAN

You will get asked for the password you set earlier. If successful, you may get a response like Warning: Your password will expire in 41 days on Fri 26 Jan 2024 12:30:09 GMT.

The klist command will show you a list of your Kerberos tickets you made with kinit.

UniFi Vpn With Active Directory and Radius

Samuel Hulme — Sat, 05 Oct 2024 00:00:00 GMT

In this guide we will set up a VPN on a UniFi network that uses a RADIUS server that is backed by Active Directory for authentication.

Step 1. Set up a RADIUS server

To use RADIUS for authentication, you must have a RADIUS server configured. The RADIUS server built into UniFi cannot be configured to use Active Directory, so an external RADIUS server is required. Here is a list of potential RADIUS servers you can use:

Microsoft Network Policy Server (NPS) Introduction guide (Windows Server only)
FreeRADIUS (Potentially Linux only? [TBC]) [^1]

[^1]: If you are using a Windows Server, you can create a Linux virtual machine using Hyper V, or with an alternative Hypervisor.

Step 2. Create a RADIUS profile in UniFi

A RADIUS profile is required to tell UniFi where to find the RADIUS server. To create a RADIUS profile, open the Network app and navigate to Settings > Profiles > RADIUS. At the bottom of the table, click Create New.

Once you have done that, you will get the form as shown in Figure 1. The options of the form that we are interested in are:

Name: This is the name RADIUS profile that will be displayed inside UniFi.
Authentication Servers: This is where you enter the IP address, Port, and Shared Secret from your RADIUS authentication servers.
Accounting: This is a checkbox that enables the Accounting Servers fields.
Account Servers: This is where you enter the IP address, Port, and Shared Secret from your RADIUS accounting servers.

In most setups, the RADIUS authentication port is 1812, the RADIUS accounting port is 1813, both IP addresses will point to the same RADIUS server, and the shared secret is what you have configured on your RADIUS server. Once you have done that, make sure to click Apply Changes at the bottom.

Step 3. Create a UniFi VPN

You can create a VPN on any UniFi Gateway by using a built-in VPN server. To do this, open the UniFi Network app, and navigate to Settings > VPN > VPN Server. Once you have done this, click Create New at the bottom of the table.

When you have done that, you will get another form, as shown in Figure 2. The options of the form that we are interested in are:

VPN Type: Make sure you use Open VPN [^2]
Name: This is the name VPN profile that will be displayed inside UniFi.
Advanced: Switch this to Manual to enable more options.
RADIUS Profile: This is a dropdown list that contains all RADIUS profiles. Choose the profile you made in step 2.
Gateway / Subnet: Use this option to configure the IP range for your VPN clients.

If your UniFi Gateway is behind another NAT (e.g., another router) then make sure to enable Use Alternate Address for Clients and then fill out the input field with the WAN IP address of that router or use a public Fully Qualified Domain Name that points to your local network.

[^2]: WireGuard does not have a RADIUS option, and L2TP is not supported by several operating systems (Ubiquiti does not recommend it).

Controlling Which Vlans UniFi Teleport Can Use

Samuel Hulme — Wed, 09 Oct 2024 00:00:00 GMT

:::important As of August 2025, Ubiquiti has released version 9.4.19 of the UniFi Network application, which collapses the "Traffic & Firewall Rules" and other rules into a single "Policy Table" interface. You need to navigate to Settings > Policy Table and toggle the Firewall type filter to manage your firewall rules. The process of creating rules remains similar, but the interface has been streamlined. - September 2025 :::

In this guide we will learn how to configure which IPs and VLANs users connected via UniFi Teleport can access.

Step 1. Identify the IP range that Teleport uses.

In order to know who we are controlling we need the know the IP range. One way to find this is to inspect a device connected with UniFi Teleport.

To do this, open the Network app and navigate to Client Devices. On this page you will find a list of all the clients and their IP address. Clients that are connected with UniFi Teleport will have the connection type of "VPN". In Figure 1 you can see I have two devices one with the IP "192.168.2.3" and "192.168.2.2", so, the subnet for this Teleport instance would be "192.168.2.0/24".

Step 2. Create an IP group with the Teleport subnet

Open the Network app and navigate to, Settings > Profiles > IP Groups, then at the bottom of the table click Create New.

Then fill out options with the following options:

Profile Name: (this can be whatever you want, I've called it "Teleport Users")
Type: IPv4 Address/Subnet
Address: (Use the subnet we found earlier, in my case its "192.168.2.0/24")

Then, press Add (to the right of the Address), and Add at the bottom of the page.

Step 3. Block Teleport from all VLANs

By default we should block Teleport from accessing all VLANs, then only allow the ones we Teleport to have.

To do this, open the Network app and navigate to Settings > Security > Traffic & Firewall Rules > Advanced. Scroll to the bottom, then press Create Entry.

Then fill out the form just like I have in Figure 3.

You can change the name to be whatever you want, and use the same Address Group you made earlier.

Step 4. Create an allowlist for Teleport.

To create an allowlist, create another IP group like we did Step 2, but instead of having the Teleport subnet, you should have all the IPs or subnets you want Teleport to have. For an example you can look at Figure 4.

Step 4.2. Create a firewall rule for the allowlist.

On the same page where we made the "Block Teleport users from LAN" rule, we should make another rule, by using a similar process like in Step 3. Then fill out the form like seen in Figure 5.

You may call the rule what ever you want, and you must make sure to use the Address Groups we made earlier.

Step 4.3. Move the allow rule above the block rule

All firewall rules are applied from the top to bottom, so if you have a block rule above an allow rule, then your block rule will take priority. So we must make sure the allowlist rule is above our blocking rule. To do this, you can grab the 6 dots icon next to the allow rule and move it above the block rule. If done successfully, it will appear like seen in Figure 6.

Using UniFi Talk with a Kamailio SIP Trunk

Samuel Hulme — Sat, 21 Jun 2025 00:00:00 GMT

In recent days, I’ve been experimenting with UniFi Talk and wanted a SIP trunk that’s not part of the PSTN - something I could play with without limitations.

What Is a SIP Trunk?

A SIP trunk is a connection to a SIP provider that handles inbound and outbound call routing - traditionally to and from the PSTN.

To simulate that environment, we’ll need to create a local SIP provider.

What Does a SIP Provider Do?

Routes calls between multiple SIP endpoints or trunks
Allocates numbers (DIDs) to subscribers
Authenticates users and prevents number hijacking

Why Kamailio?

Kamailio can handle all of these roles - it's an open-source SIP server designed for flexibility and scalability.

Setting Up Kamailio

We'll run Kamailio using Docker Compose with a minimal config.

services:
  kamailio:
    image: ghcr.io/kamailio/kamailio:6.0.1-noble
    ports:
      - 5060:5060
      - 5060:5060/udp
    volumes:
      - ./kamailio.cfg:/etc/kamailio/kamailio.cfg

There are two important things here:

Port 5060 TCP+UDP is used for SIP traffic
A kamailio.cfg file needs to be create alongside the docker compose file

My basic Kamailio config is actually borrowed from NickVsNetworking who has a great tutorial series on Kamailio configuration

Configuring UniFi Talk

Firstly we need to make sure the Static Signalling port is enabled:

Go to: Talk > Settings > System > General
Then tick the box Static Signalling Port, any number is fine but 6767 is the default.
Make sure to appropriately forward this port

Finally we can now configure the SIP trunk:

Go to: Talk > Settings > System > Third-party SIP
Create New
Set Provider to Custom
Set the provider name to whatever you want.
Add the custom fields:

Field Name	Value
`proxy`	Kamailio IP or domain
`realm`	Same as proxy
`domain`	Same as proxy
`dtmfmode`	`rfc2833`
`password`	Any placeholder (or real password if using auth)
`register`	`true`
`username`	Your E.164 phone number
`extension`	`auto_to_user`
`from-domain`	`location`
`auth-username`	Same as username

UniFi Talk expects E.164-format numbers for proper routing. For isolated, non-PSTN use, I recommend numbers like +999xxxxxxxx as +999 is reserved for testing and documentation.

Add your phone number in the Phone Numbers list.
Add the IP addresses of your Kamailio server in to the IP Address Range, if you have a single IP you can use /32 in your range.

Conclusion

You now have a fully functional, non-PSTN SIP trunk integrated into UniFi Talk. All calls will route through Kamailio just like a real SIP provider - but with no subscription, no upstream carrier, and total control.

This setup lets you:

Test call flows, IVRs, and voicemail
Simulate users and devices
Experiment with SIP signaling and Kamailio scripting
Do it all without touching the real telephone network

How I Built `mc-router`: An Enterprise-Ready Minecraft Proxy in Under 4 Hours

Samuel Hulme — Tue, 26 Aug 2025 00:00:00 GMT

:::note The article has since been updated with additional calcifications via footnotes. - September 2025 :::

In just 3 hours and 38 minutes, I built mc-router an enterprise-ready Minecraft ingress proxy designed to handle incoming connections and route them to the right backend servers. It ships with native multi-tenant support, HAProxy protocol, UDP forwarding, and even a draft cloud configuration API.

I've been trying to find a good Minecraft proxy for ingress traffic for a while now, but I've come to the conclusion that none were designed for multi-tenancy hosting environments natively - unless you workaround with your own custom plugins.

Why Build a New Proxy?

Existing Minecraft proxies are not designed for ingress, instead focusing on transferring of players to different servers mid-game. This limitation prompted the need for a new solution that could handle incoming connections efficiently while providing advanced features like cloud config synchronisation and TLS tunnelling.

Existing solutions that I evaluated:

BungeeCord - The original Minecraft proxy, known for its simplicity and ease of use. However, it lacks advanced features like TLS tunnelling and cloud configuration synchronisation.
Gate - A modern Minecraft proxy written in Go, offering better performance than BungeeCord. Gate in Lite mode is a good option for single IP but multi-server setups, but it still lacks TLS tunnelling and cloud configuration synchronisation.
Velocity - It is a popular Minecraft proxy known for its performance and scalability often utilised to allow players to switch between different worlds (each with a different backend server) mid-game. However, it lacks built-in support for TLS tunnelling and cloud configuration synchronisation.
Waterfall - A fork of BungeeCord, designed to be more stable and performant. However, it still lacks advanced features like TLS tunnelling and cloud configuration synchronisation.

Introducing `mc-router`

mc-router is a high-performance Minecraft proxy built with Rust, designed to handle incoming connections and route them to the appropriate backend servers.

Existing implemented features:

Routing based on the Handshake packet - Allows routing players to different backend servers based on the hostname they use to connect.
HAProxy Protocol v1 support - Allows passing the original client's IP address to the backend game server, which is crucial for logging and player management.
Optional UDP packet routing - Supports routing UDP packets, which is essential for a few Minecraft mods.
A config service API draft - Once completed, this will allow dynamic configuration of the proxy via a RESTful API secured with ed25519 keys. [^1]

[^1]: This API has since become a plain JSON over WebSocket service, allowing real-time updates to the proxy configuration see the code for more details.

Upcoming features:

TLS tunnelling - Enables secure connections to the backend game servers, enhancing security and privacy. [^2]
Full cloud config synchronisation - Allows the proxy to synchronise its configuration with a central cloud service, making it easier to manage multiple proxies. ... and a public roadmap with more features to come!

[^2]: TLS tunnelling will not be part of the mc-router binary itself, instead it will be implemented as a separate sidecar service that works alongside mc-router. This design choice allows for greater flexibility and modularity, enabling users to choose their preferred TLS solution without being tied to a specific implementation within the proxy.

Building `mc-router` in Under 4 Hours

The development of mc-router was a sprint, just 3 hours and 38 minutes from empty repo to a working proxy. Here’s how it unfolded:

Kickoff (16:43) — Commit 84ae854 with just a README and license. I wanted a clean structure before diving into features.
Core Routing & UDP (18:05) — Commit d2de8e7 added the first working code: modular routing based on the Minecraft handshake, plus UDP forwarding to support certain mods. At this point, mc-router could already pass traffic end-to-end.
Real-World Usability (18:24) — Commit 615f31b added HAProxy protocol support, so backend servers see the original client IPs. I also refined the config format to make the proxy easier to operate.
Toward the Cloud (20:21) — Commit ef4a554 implemented the first draft of the config service API. This was the leap from "just a proxy" to "cloud-ready infrastructure."

Conclusion

The real story isn’t just mc-router itself, it’s the speed at which it was built, the project took approximately 3 hours and 38 minutes from start to finish. The rapid development was made possible by leveraging GPT-5 to assist with coding tasks, allowing for quick iteration and problem-solving.

Enterprise-ready infrastructure software has traditionally required teams of engineers and weeks of development. With AI-assisted workflows, a single developer can produce production-grade systems in a single afternoon. — ChatGPT, August 2025

In this scenario we can agree with ChatGPT's sentiment, as GPT-5 has proven it can undertake complex software development tasks efficiently. However, human oversight and expertise remain crucial to ensure the quality and reliability of the final product.

The journey isn’t finished, next up is TLS tunnelling [^2] and completing the config service API backend, bringing mc-router even closer to its goal of being a truly enterprise-ready ingress for Minecraft.

Designing an Automated Postal Network in Minecraft

Samuel Hulme — Sun, 21 Sep 2025 00:00:00 GMT

In Minecraft, automation is a key aspect of enhancing gameplay and efficiency. One such use is building an automated postal network that can transport items between different locations in the game. By using Lua scripting provided by the CC: Tweaked mod, we can create a system that can handle item transportation in a structured manner, inspired by real-world networking concepts like the TCP/IP Model .

How does networking relate to item transportation?

In computer networking, data is transmitted across networks using a layered approach, as defined by the TCP/IP Model . Each layer has specific responsibilities and standards, from physical transmission to application-level protocols. @cite{fortinet2025} Similarly, in Minecraft, we can think of item transportation as a multi-layered process:

Link Layer (Transport method): This layer is the physical act of sending and receiving of items. Whether it is through minecart tracks, hoppers, or even Trains from the Create mod it does not matter. This is similar to how network data can travel through Ethernet cables or Wi-Fi in real-world networking. @cite{fortinet2025}
Internet Layer (Postcodes and addresses): This layer ensures that items are correctly transferred to the destination by routing between networks. For Minecraft, we will create a system that uses item name addresses (more on this later) to ensure that items are routed correctly.
Transport Layer This layer is typically responsible for packet splitting, sequencing and reassembly @cite{fortinet2025}. However in Minecraft this would require automated item renaming to create individual packages, which is not possible. @cite{tweaked2025}
Application Layer (The package contents): This is the actual payload the user wants to send. In real-networking thi is the application data like HTTP, FTP, etc. @cite{fortinet2025} In our case, this is the item itself, such as diamonds, iron ingots, or any other item in Minecraft.

Package addressing

When sending items through our postal network, we need a way to address them correctly. In real-world postal systems, this is done using addresses and postcodes. In our Minecraft postal network, we will get players to rename items to include their destination address.

We will use the following format where the largest geographical area is listed first, down to the most specific location:

Country:State:City:Street:HouseNumber

The format is flexible one can include as many or as few levels as they want, but the order must be maintained. For example:

SheepLand:Northshire:Sheepville:Wool St:1 - A full address including country, state, city, street, and house number.
SheepLand:Northshire:Sheepville - A more general address that only includes the country, state, and city. This means the item will be delivered to a central location in Sheepville.
SheepLand - The most general address, only specifying the country. This could be used for items that are to be delivered to a central hub in the country.
Northshire:Sheepville - An address that omits the country, assuming it is within the same country as the sender.

Why use item names and geographical areas for addressing?

Compatible with Minecraft: Using item names for addressing is straightforward and easy to implement within the constraints of Minecraft's item system.
Supports Scripting: We can programmatically read item names using Lua scripts in CC: Tweaked, making it easy to extract the address information.
Less error prone: It is impossible to rename items pragmatically, so players must manually set the address with an Anvil. By choosing a human readable format, we reduce the chances of errors in addressing. Its also the very reason why DNS (Domain Name System) exists in real-world networking which turns domain names into IP addresses. @cite{fortinet2025a}
Hierarchical: Using geographical areas allows for a hierarchical addressing system, similar to real-world postal systems, which can help in routing items efficiently.
Backwards compatibility with existing addressing formats: For example TreeLand:dsffddfhfd7d8 which uses a TreeLand specific format of dsffddfhfd7d8, however one may need automated item renaming to strip the global prefix once the package arrives in TreeLand, which is something both Minecraft or CC: Tweaked do not support natively. @cite{tweaked2025}

Address Registration and Validation

It is inevitable that players will make mistakes when renaming items. To mitigate this, we can implement a validation system that checks the address format before processing the item for delivery.

We will build an address book that contains all valid geographical areas and how they are linked together. This will work similar to how routers use routing table in computer networking @cite{cloudflare2025}.

When an item is processed, the system will check the address against this address book to ensure it is valid. If the address is invalid, the shipment would not be sent.

Furthermore, the address book could be decentralised, meaning each location could maintain a list of neighbouring locations. This would allow for a more dynamic and scalable addressing system, as locations could be added or removed without needing to update a central database.

However, this would require a protocol similar to BGP (Border Gateway Protocol) used in real-world networking to exchange routing information about which networks connect to each other. @cite{cloudflare2025}

Package assembly and transport

Package Preparation:

To send a item, the player would first rename it with the desired address using an Anvil. The item would then be placed into a designated "outgoing" chest connected to a Computer.
The Computer would run a Lua script that scans the chest for items, validates their addresses using the address book.

Routing through hubs:

The script would determine the best route for each package based on the address. This involves sending the package to the next hub in the route towards the destination.
Each hub would have its own Computer running a similar script that handles incoming packages, checks their addresses, and forwards them to the next hop in the route.
Form earlier, we know each hub would maintain a list of neighbouring hubs to facilitate routing known as an address book.

Final Delivery:

Once a package reaches its destination hub, the script would check if the address matches the local area. If it does, the package would be shipped to the final destination in the area, similar to how a router delivers packets to a client on a local area network.
If the address does not match, the package would be stored as lost mail, and the player would need to contact the hub operator to retrieve it.

Conclusion and what's next?

By taking inspiration from real-world networking concepts and using Lua scripting in CC: Tweaked, we can create an automated postal network in Minecraft that efficiently transports items between locations. This system not only enhances gameplay but also provides a fun and educational way to learn about networking principles. The next article in this series will cover the address book and routing protocols in more detail.

Increasing Context Size of Docker Model Runner The Right Way

Samuel Hulme — Sun, 19 Oct 2025 00:00:00 GMT

Docker Model Runner uses a default context size of 4096 tokens, which is insufficient for many modern AI/ML applications that require larger context windows to function effectively.

There are many well-documented solutions, however none are straightforward or reliable, for example there is an attempt to use cagent with Docker Model Runner to increase context size, but in my experience the new context size is temporarily applied to the cagent process only, and not applied by default to the specific model itself.

However, the official Docker documentation only mentions how you can set the context size through compose files, but again, that only applies to the model instance in the compose project, not the default model context size globally.

Looking at these options, one might assume that no reliable method exists to change the default context size of Docker Model Runner globally. But let's dig deeper - there is a solution!

Introducing the `docker-model` CLI

There is actually a somewhat unknown CLI tool that lives in the Docker Model Runner repo. This tool allows you to manage and configure models directly, including setting the default context size for any model.

Let's install the docker-model CLI tool:

First, navigate to the Docker Model Runner repository with a web browser.
Navigate to the Actions tab.
Select the Build model-cli workflow from the left sidebar.
Click on the latest successful workflow run.
Scroll down to the "Artifacts" section and download the dist artifact.
Extract the downloaded ZIP file to a directory of your choice.
The archive will contain multiple directories for different operating systems and architectures. Navigate to the directory that matches your system (e.g., windows-amd64 for Windows on AMD64 architecture).
Inside this directory, you will find the docker-model executable. You can move this executable to any directory (and optionally add it to your system's PATH for easier access).

Changing the Default Context Size

If you have already installed models through Docker Desktop, then you can list the installed models using the docker-model CLI:

docker-model.exe list

It will output something like this:

MODEL NAME  PARAMETERS  QUANTIZATION    ARCHITECTURE  MODEL ID      CREATED       SIZE
smollm3     3.08 B      IQ2_XXS/Q4_K_M  smollm3       9bff8b097a33  3 months ago  1.78 GiB
gpt-oss                                               e233e4483f51  2 months ago
phi4        14.66 B     IQ2_XXS/Q4_K_M  phi3          03c0bc8e0f5a  6 months ago  8.43 GiB

Now to change the default context size of a specific model, use the configure command along with the --context-size flag. For example, to set the context size of the smollm3 model to 8192 tokens, run the following command:

docker-model.exe configure smollm3 --context-size 8192

Don't be fooled by the lack of command output - if it is silent then it has worked! You have successfully changed the default context size of the smollm3 model to 8192 tokens.

The best part is that, unlike cagent, which only initiates temporary sessions, and Compose, which defines per-project settings, docker-model talks directly to the Model Runner daemon’s persistent configuration.

Conclusion

By using the docker-model CLI tool, you can easily and reliably change the default context size of Docker Model Runner models without the need for complex workarounds like cagent or Compose files. This method ensures that your models can handle larger context sizes globally, improving their performance and capabilities for various AI/ML applications. It's a reminder that even in well-documented systems, there are often hidden gems waiting to be discovered!

From Cubes to Kubes: Starting a Cloud-Native Foundation for Miners Online in One Month

Samuel Hulme — Sat, 25 Oct 2025 00:00:00 GMT

Few projects in the tech world are as exhilarating and challenging as starting brand new cloud-native architecture from scratch. In this post, I will share my experience of transforming Miners Online, my Minecraft server running since 2017, from a traditional server setup to a cloud-native architecture with a prototype Kubernetes deployment all within the span of one month.

The Beginning: Why Rebuild Everything?

For Miners Online, we have big plans for the future. The reasons are simple, to attract a player base we need something innovative, and interesting to offer.

The existing infrastructure, which consisted of:

multiple repositories for each game and package
on-premises CI/CD pipelines and Maven repositories
manual process to deploy updates to the server

was becoming a bottleneck for growth and innovation.

While this setup was functional, it was becoming increasingly difficult to manage and scale. With the rise of cloud-native technologies, I saw an opportunity to not only modernise our setup but also to leverage the benefits of scalability, resilience, and ease of management that Kubernetes offers.

The dependencies

Before diving into the rebuild, I took stock of the existing dependencies and tools that would be part of the new architecture:

Kubernetes: The backbone of the new architecture, providing orchestration for containerised applications.
Helm: For managing Kubernetes applications and simplifying deployments.
Docker: To containerise the various services and applications.
GitHub Actions: For CI/CD pipelines to automate testing and deployment.
GitHub Container Registry: To store and manage Docker images.
GitHub Projects: For project management and tracking progress.
Agones: A high-performance game server hosting solution that integrates well with Kubernetes.
Shulker: A Minecraft Kubernetes operator to manage Minecraft server instances.
Minestom: A lightweight Minecraft server implementation that allows for custom game development.

With these tools in mind, I set out to rebuild Miners Online from the ground up.

Step 1: Establishing the Monorepo

Starting on October 7th, the first step was to scrap all existing repositories and start from scratch with a monorepo approach. Whilst a nuclear option, this resulted in an empty canvas the Miners Online monorepo which can be carefully built upon with planning (which planning was certainly lacking before).

I started by documenting the philosophy and structure of the monorepo, ensuring that it would be easy to navigate and maintain. This included setting up directories for each game, different services, and shared packages.

Step 2: Building the first games and packages

On the evening of October 7th, I began the process of creating the first games with Minestom and packages within the monorepo. I started with designing the lobby as it is quite minimal and can revel what shared packages are needed for other games. By October 8th, I had the lobby and a few essential packages set up including basic world management and schematic loading.

Step 3: Containerising with Docker with GitHub Actions

With the lobby and packages in place, I spent the next day (October 9th), containerising the application using Docker. I created a Dockerfile for the lobby and set up a GitHub Actions workflow to automate the build and push process to the GitHub Container Registry. This allowed for easy testing and deployment of the application.

Step 4: Further game development

Between October 10th and 12th, I made multiple improvements including:

Block entity support in schematics
Sign based game object creation
Basic NPC implementation
Environment variable support for configuration
Simplification of the Docker build pipeline
Demo Django project for future API services

These enhancements were crucial for creating better game experiences and ensuring that the server could be easily configured.

Step 5: Kubernetes and Agones integration

On October 22nd, I began the process of integrating Kubernetes and Agones into the architecture. I used GitHub Copilot to generate the initial Helm charts and deployment configurations. However Copilot made many mistakes and ignored me many times, so I guided it through the correct configurations and best practices.

Currently the Kubernetes deployment is in a prototype state, with game servers using Paper MC instead of Minestom for testing purposes. These will be updated to use Minestom once the game development is more mature.

Step 6: Managing Minecraft servers with Shulker

To manage the Minecraft server instances, I decided to use Shulker, a Kubernetes operator specifically designed for Minecraft.

However, there is a version incompatibly between Shulker and the latest Minestom release which I resolved by submitting a pull request (PR) to Shulker - I have already contributed to Shulker in the past.

Shulker was stuck with an old Minestom version (the 1_21-9219e96f76 snapshot) for a while, that did not support the latest Auth API changes in Minestom. I redesigned Shulker's Minestom SDK and choose the last Minestom version (2025.10.05-1.21.8) to support Java 21 - as Shulker builds with Java 21 I could not use the actual latest Minestom version (2025.10.18-1.21.10) which supports Java 25+ only. As of writing this post, the PR is still unmerged, which means I am unable to use the Shulker SDK in my games and as a result unable to deploy any games to the cluster.

Step 7: Project management and tracking progress

On October 23rd, I set up a public roadmap on GitHub Projects to manage and track the progress of the rebuild.

Introducing project management practices after most of the work was done, will help to keep future development organised and ensure that tasks are prioritised effectively.

Furthermore, a public roadmap allows the community to see what is planned and contribute ideas or feedback.

Conclusion: Reflecting on the Journey

Rebuilding Miners Online from scratch into a cloud-native architecture using Kubernetes in just one month has been an intense but rewarding experience. While there is still much work to be done, the foundation has been laid for a more scalable, resilient, and manageable infrastructure.

What's next? The immediate next steps involve:

Waiting for the Shulker PR to enable Minestom support
Integrating the Shulker SDK into the games
Testing and deploying the games to the Kubernetes cluster

This journey has not only modernised Miners Online but also provided valuable insights into cloud-native technologies and best practices. I look forward to continuing this journey and sharing more updates in the future.