Initial commit

1 files changed, 132 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d6c83dc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,132 @@
+# tyil.net
+
+The collection of servers and clients in Tyil's network.
+
+## Architecture
+
+The network consists of machines which may or may not be remotely accessible by
+public IP. The main form of interconnectivity is done through the VPN, which
+should be installed on all machines, together with SSH.
+
+### Network Layout
+
+The network's CIDRs are `10.57.0.0/16` for IPv4, and `fd14:199c:e514::/48` for
+IPv6. These are then divided in specific categories.
+
+Category     | IPv4 Range     | IPv6 Range
+-------------+----------------+-------------------------
+Workstations | 10.57.100.0/24 | fd14:199c:e514:1::/64
+Servers      | 10.57.20.0/24  | fd14:199c:e514:2::/64
+
+## Bootstrap
+
+Ensure you have a POSIX-compliant system, with `bash` and `git` available in
+your `$PATH` as well.
+
+    # Clone the repository
+    git clone https://git.tyil.nl/tyilnet /usr/tyilnet
+
+    # Bootstrap the main application
+    /usr/tyilnet/bin/tyilnet bootstrap
+
+The bootstrap command will also configure a cronjob to run `tyilnet sync` every
+2 hours.
+
+## Set
+
+For machine-specific configuration that can't be shared in the repository,
+private configuration values can be set using `tyilnet set`. The first
+parameter to this command is the key, the second parameter is the value. You
+probably want to ensure this command is not visible in your shell history.
+
+## SSH
+
+The `ssh` action will enumerate all hosts that are configured in this
+repository at `etc/hosts`, and run the given command over ssh on each of these.
+
+    tyilnet ssh <command>
+
+## Services
+
+### Backup
+
+Backups are made using `borg` and `borgmatic`. The backups are pushed to a
+backup server over the VPN. The database backups (using `borg`) are done on the
+fly, but filesystem backups (using `borgmatic`) require a configuration file to
+be created. This is handled in the bootstrap subaction.
+
+    tyilnet backup/bootstrap
+
+If an error shows about a missing configuration value, you most likely didn't
+set the encryption key. This can be set using `tyilnet set`.
+
+    tyilnet set borg.key.$FQDN.hostfs <encryption-key>
+
+If the machine is also hosting databases, encryption keys for those may need to
+be set too.
+
+Once preconfiguration is done, you can run the actual backups using the
+`backup` command.
+
+    tyilnet backup
+
+Synchronization of the `borgmatic` configuration file is handled by `tyilnet
+backup/sync`, which is called on `tyilnet sync` automatically once the backup
+process has been bootstrapped. The bootstrap subaction will also configure a
+cronjob.
+
+### Metrics
+
+Every node in the network should export metrics for use by Prometheus. This
+action will set this up.
+
+    tyilnet metrics/bootstrap
+
+### Metrics Server
+
+To complement the metrics being made available, a server needs to gather them.
+This is done with Prometheus, and this service can be kept up-to-date through
+`tyilnet` as well
+
+    tyilnet metrics-server/bootstrap
+
+This will install and configure Prometheus, and register it to keep the
+configuration in check.
+
+### Shell
+
+All the configuration to make the shell a joy are in this action. To set it up,
+run the bootstrap subcommand for it.
+
+    tyilnet shell/bootstrap
+
+This will make the running user's `$HOME` a repository of
+`https://git.tyil.nl/dotfiles`, including all shell-related configuration
+contained therein, and configure `ssh`. The `shell/sync` command will ran
+whenever `tyilnet sync` is ran.
+
+### SSL
+
+All functionality to manage the SSL infrastructure for tyil.net. This requires a
+CA certificate to exist before it can be bootstrapped, but should also be
+included in this repository anyway. If there's no CA certificate yet, create one
+with the `ca` subcommand.
+
+    tyilnet ssl/ca
+
+Afterwards, you can bootstrap this service on all machines, which will install
+the CA certificate into the OS's SSL certificate store.
+
+    tyilnet ssl/bootstrap
+
+The `sync` subcommand will update the CA certificate as needed, and will run
+whenever `tyilnet sync` is ran.
+
+### VPN
+
+Bootstrap the required configuration for the VPN.
+
+    tyilnet vpn/bootstrap
+
+The `vpn/sync` step will be ran whenever `tyilnet sync` is ran, and thus should
+update automatically.