Update README.md

README.md

@@ -1,6 +1,21 @@
 # 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.
+mileage may vary if you change the intended network driver for Docker. There are a few caveats to how this is designed: 
+
+- Some configuration is managed through `config.env` and exported to the Docker container as environment variables; This can help with convergence of configuration 
+  between hosts but results in a configuration that cannot be changed with a simple `/quote REHASH`.
+- inspircd autoloads any `.conf` file from the `custom/` directory (it's mapped into the container from the `docker-compose.yml` file.
+- Environment variables are referenced in the configuration files using `&env.ENV_VAR_NAME;` and this usage can be found throughout the configuration.  
+- Changing the `config.env` means that the container must be re-created: `docker-compose up -d`
+
+When editing configuration, use generated passwords everywhere possible: 
+
+```
+echo $(dd if=/dev/urandom bs=1024 count=1 status=none | sha256sum | base64 | head -c 64
+```
+
+Some passwords need to be consistent (uplink send/recv passwords for example) across servers. A subject for improvement would be not using the environment
+for unencrypted passwords, see [#TODO](#TODO) section for more info on how this can be improved. 
 
 ## Hub
 - copy `config.env.example` to `config.env` and edit 
@@ -9,7 +24,8 @@ mileage may vary if you change the intended network driver for Docker.
 ### 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:
+to the [#external-tls](#external-tls) section under [#leaf-servers](#leaf-servers) for more info. To bootstrap internal TLS with an `easyrsa3` 
+CA perform the following:
 
 - cd to `easyrsa3` directory
 - `./easyrsa init-pki`
@@ -72,6 +88,10 @@ create a `custom/links.conf`. The following describes a declaration for a leaf c
 - 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`.)
 
+### Uplink (to hub)
+Currently, this is setup for the hub to uplink to leaf servers, but the opposite can be provided with a `<link>` block in the
+`include.conf`.
+
 ### External TLS
 - Copy your issued certificate and key to `custom/irc.crt` and `custom/irc.key` respectively
 - Add the following to `custom/include.conf`: 
@@ -89,7 +109,7 @@ the leaf server (these files go in `custom/` and should also be named `server.cr
             provider="gnutls">
 ```
 
-and also change the bind for `6697` to use the `supernets_ssl` SSL profile: 
+and also change the bind for `6697` to use the `supernets_ssl` profile: 
 
 ```
 <bind address="*"
@@ -98,7 +118,9 @@ and also change the bind for `6697` to use the `supernets_ssl` SSL profile:
       type="clients">
 ```
 
-### Tor hidden service 
+### Tor hidden service
+If you don't want Tor, skip to [#leaf-servers-continued](#leaf-servers-continued)
+
 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: 
 
@@ -111,6 +133,19 @@ docker exec -it tor-tor-1 cat /var/lib/tor/ircd/hostname
 q6ihxyqviqz76xt6dcpvgidbal64ltbvptbjp4yoxyjihgmqpxugcbid.onion
 ```
 
+HAProxy is necessary in this case because Tor's `HiddenServiceExportCircuitID` uses PROXY protocol v1 and inspircd uses PROXY protocol v2, HAProxy supports both: 
+
+```
+frontend tor-north
+  bind                 127.0.0.1:19818 accept-proxy
+  mode                 tcp
+  default_backend      inspircd-south
+
+backend inspircd-south
+  mode   tcp
+  server inspircd 127.0.0.1:7001 send-proxy-v2
+```
+
 - cd to `haproxy/`
 - `docker-compose up -d`
 - By default, the inspircd `include.conf` should already provide the necessary configuration:
@@ -173,19 +208,38 @@ q6ihxyqviqz76xt6dcpvgidbal64ltbvptbjp4yoxyjihgmqpxugcbid.onion
 
 This unfortunately requires two connect blocks due to how HAProxy support works on inspircd4 (this seems to work differently from inspircd3.)
 
-There is no TLS for Tor connectivity because Tor hidden services are already encrypted. There are no authorities which issue certificates 
-for `.onion` domains either. There is no reason to use TLS with a Tor hidden service. To connect to the service: 
-
 #### Onionbalance v3 
 - This is not configured, but I will consider adding it to the Tor configuration if its of interest: https://onionservices.torproject.org/apps/base/onionbalance/v3/tutorial/
 `HiddenServiceOnionbalanceInstance` would essentially allow multiple leaf servers to provide Tor access using the same `MasterOnionAddress`
 but requires a shared secret between leaf server Tor instances.
 
+There is no TLS for Tor connectivity because Tor hidden services are already encrypted end-to-end. To connect to the hidden service: 
+
 ```
 proxychains4 irssi 
 /connect q6ihxyqviqz76xt6dcpvgidbal64ltbvptbjp4yoxyjihgmqpxugcbid.onion 6668
 ```
 
+After connecting the user will have an address that is unique to the circuit ID that is in use:
+
+```
+1:08 -!- sq_ [~stelleri@4m4l237j:f6jtvjrf:n6du6chj:hidden]
+11:08 -!-  ircname  : User irc
+11:08 -!-  hostname : ~irc@fc00:dead:beef:4dad::5e fc00:dead:beef:4dad::5e
+11:08 -!-  channels : #tor
+11:08 -!-  server   : miami.supernets.org [internet relay chat network]
+11:08 -!-  modes    : +ix
+11:08 -!-           : * is connecting from an unknown autonomous system
+11:08 -!-           : * is connecting from an unknown country
+11:08 -!-  idle     : 0 days 0 hours 46 mins 44 secs [signon: Sun Jan  5 17:22:28 2025]
+11:08 -!- End of WHOIS
+```
+
+## Leaf servers (continued) 
+- chown -R 999 custom/
+- docker-compose build
+- docker-compose up -d
+
 ## Atheme services
 To configure Atheme, add the following to `custom/links.conf` on the hub server:
 
@@ -215,3 +269,22 @@ Note that it does not specify TLS in this case, that's provided with `stunnel`:
 - `docker-compose build`
 - `docker-compose up -d`
 - Refer to https://github.com/supernets/atheme/tree/master for Atheme configuration instructions.
+
+# Administration 
+- OPER: `/oper admin <password@config.env>`
+- OJOIN Override any channel restriction to join: `/quote ojoin #services`
+- SNOMASKS are configured to log to `#opers`
+
+## Debugging 
+- To start inspircd with debugging, add `-d` to `DAEMON_FLAGS` in `config.env`
+- `docker-compose up -d`
+- `docker logs -f inspircd-ircd-1`
+
+# TODO
+- The `password_hash` in conjunction with the `PBKDF` module can be used to produce hashed passwords which can be used in configuration: https://docs.inspircd.org/3/modules/password_hash/ this unfortunately as it is now assumes that you already have a server running and can use `/MKPASSWD` to create passwords.
+
+- Using `docker-compose up --no-start` will create the container but not start it. This is useful if prior to starting the container more configuration needs
+  needs to be completed, it maps all of the volumes / files needed, etc. This also allows you to use `docker-compose run` on the created container, but won't
+  start the container; for running one-off commands that are not pertinent to the container's primary purpose. If inspircd provided some functionality like
+  creating password hashes or generating certificates from the inspircd executable this would be really useful.
+