From 9a211eb3b106e14da8b054c5f3aa7388168d5f9d Mon Sep 17 00:00:00 2001 From: paige Date: Sun, 5 Jan 2025 15:58:17 +0000 Subject: [PATCH] update documentation --- README.md | 202 ++++++++++++++++++++++++++++++++++++++++--- include.conf.example | 13 +-- stunnel/stunnel.conf | 4 +- 3 files changed, 193 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index b65da9f..f3dbf07 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,202 @@ -# Instructions +# Getting started +This docker configuration relies on the host network driver meaning it doesn't setup any internal networks or even a separate NetNS. Your +mileage may vary if you change the intended network driver for Docker. -## docker-compose -1. copy `config.env.exmaple` to `config.env` and edit -2. copy `include.conf.example` to `custom/include.conf` -3. follow steps from [#easyrsa] section -4. `docker-compose build` -5. `docker-compose up -d` +## Hub +- copy `config.env.example` to `config.env` and edit +- copy `include.conf.example` to `custom/include.conf` and edit (don't delete) as much as possible for now + +### Internal TLS +The following steps describe how to setup `easyrsa3` for internal TLS. This step is necessary regardless of whether you intended to use +issued certificates for leaf servers because it provides TLS encryption between the hub and it's leaf servers and between services. Refer +to the external TLS section for leaf servers for more info. To bootstrap internal TLS with an `easyrsa3` CA perform the following: -# easyrsa -On the hub: - cd to `easyrsa3` directory -- `./easyrsa init-pki` +- `./easyrsa init-pki` - `./easyrsa build-ca` - `./easyrsa build-server-full hub.stuff.ts.net` +- `./easyrsa build-server-full leaf1.stuff.ts.net` +- `./easyrsa build-server-full services.stuff.ts.net` - `./easyrsa gen-crl` - `./easyrsa gen-dh` The `.gitignore` takes care of keeping secrets out of the git repo: +There are two directories under `easyrsa3/pki/`: `issued/` and `private/`. The former contains certificates and the latter contains keys: - copy `ca.crt`, `crl.pem`, and `dh.pem` to `custom/` +- copy hub cert and key to `custom/server.crt` and `custom/server.key` (the server cert and key are named `hub.stuff.ts.net.crt` and `hub.stuff.ts.net.key` +depending on the FQDN used to create the certificate. + +The default `include.conf` example already refers to `custom/server.crt` and `custom/server.key` for the `defaultssl` profile: + +``` + +``` + +## Hub (continued) +create a `custom/links.conf`. The following describes a declaration for a leaf configuration: + +``` + +``` - `chown -R 999 custom/` -- copy hub cert and key to `custom/server.crt` and `custom/server.key` -- manually copy certs and keys as well as `dh.pem` to each leaf. +- `docker-compose build` +- `docker-compose up -d` + +## Leaf servers +- copy `config.env.example` to `config.env` and edit +- copy `include.conf.example` to `custom/include.conf` and edit (don't delete) as much as possible for now + +### Internal TLS +- Copy certificate and key as well as `ca.crt` and `dh.pem` from the `easyrsa3` CA (probably located on the hub server) to +the leaf server (these files go in `custom/` and should also be named `server.crt` and `server.key`.) + +### External TLS +- Copy your issued certificate and key to `custom/irc.crt` and `custom/irc.key` respectively +- Add the following to `custom/include.conf`: + +``` + +``` + +and also change the bind for `6697` to use the `supernets_ssl` SSL profile: + +``` + +``` + +### Tor hidden service +Tor can be configured with HAProxy between inspircd and Tor to identify clients based on their circuit ID; therefore a ULA-based IPv6 +hostmask can be assigned to help identify each unique client: + +- cd to `tor/` +- `docker-compose up -d` +- To get the hidden service hostname: + +``` +docker exec -it tor-tor-1 cat /var/lib/tor/ircd/hostname +q6ihxyqviqz76xt6dcpvgidbal64ltbvptbjp4yoxyjihgmqpxugcbid.onion +``` + +- cd to `haproxy/` +- `docker-compose up -d` +- By default, the inspircd `include.conf` should already provide the necessary configuration: + +``` + + + + + + + +``` + +## Atheme services +To configure Atheme, add the following to `custom/links.conf` on the hub server: + +``` + +``` + +Atheme also requires the following to be added to `custom/include.conf`: + +``` + +``` + +Note that it does not specify TLS in this case, that's provided with `stunnel`: + +- cd into the `stunnel/` directory +- edit `stunnel.conf` +- `docker-compose build` +- `docker-compose up -d` +- Refer to https://github.com/supernets/atheme/tree/master for Atheme configuration instructions. diff --git a/include.conf.example b/include.conf.example index 46eb8f1..6341455 100644 --- a/include.conf.example +++ b/include.conf.example @@ -13,17 +13,6 @@ requestclientcert="yes" provider="gnutls"> - - @@ -103,7 +92,7 @@