How I set up an IRC daemon on Kubernetes

Published on , 1480 words, 6 minutes to read

IRC. It's one of the last bastions of the old internet, and still an actively developed and researched protocol. Historically, IRC daemons have been notoriously annoying to set up and maintain. I have created an IRC daemon running on top of Kubernetes, which will hopefully help remove a lot of the pain points for my personal usage. Here's how I did it.

IRC is a simple protocol and only has a few major moving parts. IRC is made up of networks of servers that federate together as one logical unit. IRC is scalable from networks spanning one server to hundreds (though realistically you're not likely to find more than about 10 servers in a network).

At its core, IRC daemons are a pub-sub protocol that also has a distributed state layer on top of it. TCP connections can either represent individual users or server trunking. Each user has their own state (nickname, ident and "real name"). Users can join channels which can have their own state (modes, topic, timestamp and ban lists). Some servers have a limit of the number of channels you can join.

So, with this in mind, let's start with a simple IRC daemon in a docker container. I chose ngircd for this because it's packaged in Alpine Linux. Let's create the configuration file ngircd.conf:

Name =
AdminInfo1 = ShadowNET Main Server
AdminInfo2 = New York, New York, USA
AdminInfo3 = Xe Iaso <>
Info = Hosted on Kubernetes!
Listen =
MotdFile = /shadownet/motd
Network = ShadowNET
Ports = 6667
ServerGID = 65534
ServerUID = 65534

MaxJoins = 50
MaxNickLength = 31
MaxListSize = 100
PingTimeout = 120
PongTimeout = 20

AllowedChannelTypes = #&+
AllowRemoteOper = yes
CloakUserToNick = yes
DNS = no
Ident = no
IncludeDir = /shadownet/secret
MorePrivacy = yes
NoticeBeforeRegistration = yes
OperCanUseMode = yes
OperChanPAutoOp = yes
PAM = no
PAMIsOptional = yes
RequireAuthPing = yes
# WebircPassword is set in secrets

Name = #lobby
Topic = Welcome to the new ShadowNET!
Modes = tn

Name = #help
Topic = Get help with ShadowNET | Ping an oper for help
Modes = tn

Name = #opers
Topic = Oper hideout
Modes = tnO

This is mostly based on the default settings in the example configuration file with a few glaring exceptions:

So, let's create a dockerfile for this:

FROM xena/alpine
COPY motd /shadownet/motd
COPY ngircd.conf /shadownet/ngircd.conf
RUN apk --no-cache add ngircd
CMD ["/"]

motd is a plain text file that is used as the "message of the day" when users connect. Servers usually list their rules here. My motd has some ascii art and has this extra info:

The *new*!

Connect on port 6667 or r4qrvdln2nvqyfbq.onion:6667

- Don't do things that make me have to write more rules here
- This rule makes you breathe manually

Now you can build and push this image to the docker hub.

You may have noticed earlier that a comment in the config file mentioned [webirc][webirc]. This is important for us because IRC server normally assume that the remote host information in socket calls is accurate. My Kubernetes setup has at least one level of TCP proxying at work, so this cannot pan out. Webirc offers an authenticated mechanism to let a proxy server lie about user IP addresses. My nginx-ingress setup uses the haproxy PROXY protocol to let underlying services know client IP addresses. So what we need is an adaptor from haproxy PROXY protocol to webirc. I hacked one up:

package main

import (

	_ ""
	irc ""

var (
	webircPassword = flag.String("webirc-password", "", "the password for WEBIRC")
	webircIdent    = flag.String("webirc-ident", "snet", "the ident for WEBIRC")
	webircHost     = flag.String("webirc-host", "", "the host to connect to for WEBIRC")
	port           = flag.String("port", "5667", "port to listen on for PROXY traffic")

func main() {

	list, err := net.Listen("tcp", ":"+*port)
	if err != nil {

	log.Printf("now listening on port %s, forwarding traffic to %s", *port, *webircHost)

	proxyList := &proxyproto.Listener{Listener: list}

	for {
		conn, err := proxyList.Accept()
		if err != nil {
		go dataTo(conn)

func dataTo(conn net.Conn) {
	defer conn.Close()

	ip, _, err := net.SplitHostPort(conn.RemoteAddr().String())
	if err != nil {
		log.Printf("what, can't split remote address: %v", err)
		ev := irc.Message{
			Command: "QUIT",
			Params: []string{

		fmt.Fprintln(conn, ev.String())

	peer, err := net.Dial("tcp", *webircHost)
	if err != nil {
		log.Println(*webircHost, err)
	defer peer.Close()

	spip := strings.Split(ip, ".")

	hostname := strings.Join([]string{
		Hash("snet", spip[0])[:8],
		Hash("snet", spip[0] + spip[1])[:8],
		Hash("snet", spip[0] + spip[1] + spip[2] + spip[3])[:8],
	}, ".")

	ev := irc.Message{
		Command: "WEBIRC",
		Params: []string{
	fmt.Fprintf(peer, "%s\r\n", ev.String())

	go io.Copy(conn, peer)
	io.Copy(peer, conn)

// Hash is a simple wrapper around the MD5 algorithm implementation in the
// Go standard library. It takes in data and a salt and returns the hashed
// representation.
func Hash(data string, salt string) string {
	output := md5.Sum([]byte(data + salt))
	return fmt.Sprintf("%x", output)

This proxies connections from incoming TCP sockets to the IRC server. It also creates a fancy hostname for ngircd to use when people do a /whois on users. ngircd does have its own cloaking mechanism (which I am not using here), but I figure doing the splitting on IP address classes will make a more easy way to reliably ban users from channels.

Now, let's build this as a docker image and push it to the docker hub:

FROM xena/go:1.13.5 AS build
WORKDIR /shadownet
COPY go.mod .
COPY go.sum .
RUN go mod download
COPY cmd ./cmd
RUN GOBIN=/shadownet/bin go install ./cmd/proxy2webirc

FROM xena/alpine
COPY --from=build /shadownet/bin/proxy2webirc /usr/local/bin/proxy2webirc
CMD ["/usr/local/bin/proxy2webirc"]

And now we get to wire this all up in a kubernetes manifest. Let's create a namespace:

# 00_namespace.yml
apiVersion: v1
kind: Namespace
  name: ircd

And now we need to create the secrets that the IRC daemon will use when operating. We need the webirc password and a few operator blocks. Let's make a script to create operator blocks:

# scripts/

echo "[Operator]
Name = $1
Password = $(uuidgen)"

Then let's use it to create a few operator configs:

$ scripts/ Cadey >> opers.conf
$ scripts/ h >> opers.conf

And then create the webirc password:

$ echo "[Options]
WebircPassword = $(uuidgen)" >> webirc.conf

And then let's load these into a yaml file:

# 01_secrets.yml
apiVersion: v1
kind: Secret
  name: config
  namespace: ircd
type: Opaque
  opers.conf: |
    <contents of opers.conf>
  webirc.conf: |
    <contents of webirc.conf>

Now all we need is the irc daemon deployment itself that ties this all together:

# 02_ircd.yml
apiVersion: apps/v1
kind: Deployment
  name: ircd
  namespace: ircd
    app: ircd
  replicas: 1
      name: ircd
        app: ircd
      - name: proxystrip
        image: shadownet/proxy2webirc:latest
        imagePullPolicy: Always
        - containerPort: 5667
          name: proxiedirc
          protocol: TCP
        - name: WEBIRC_HOST
        - name: WEBIRC_PASSWORD
          value: <password from webirc.conf>
      - name: ircd
        image: shadownet/ircd:latest
        imagePullPolicy: Always
        - name: secretconfig
          mountPath: "/shadownet/secret"
      restartPolicy: Always
      - name: secretconfig
          secretName: config
      app: ircd
apiVersion: v1
kind: Service
  name: ircd
  namespace: ircd
    app: ircd
  - port: 6667
    targetPort: 5667
    protocol: TCP
    app: ircd
  type: NodePort

This will set up our IRC daemon to read the secrets from the filesystem at /shadownet/secret, which was configured as the IncludeDir in the ngircd config above.

At this point, your IRC daemon is ready to go and can be applied to your cluster whenever you want, however it may be interesting to set up a tor onion address for the IRC server. Using the tor operator, we can create a private key locally, load it as a kubernetes secret and then activate the tor hidden service:

$ openssl genrsa -out private_key 1024
$ kubectl create secret -n ircd generic ircd-tor-key --from-file=private_key

Now apply this manifest:

# 03_onion.yml
kind: OnionService
  name: ircd
  version: 2
    app: ircd
    - targetPort: 6667
      publicPort: 6667
    name: ircd-tor-key 
    key: private_key

Now, you should be able to let users connect to your IRC server to their heart's content. If you want to join the IRC server I've set up, point your IRC client at I'll be in #lobby.

Facts and circumstances may have changed since publication. Please contact me before jumping to conclusions if something seems wrong or unclear.

Tags: irc, kubernetes