From e281eedb6f6e0fda791a45145f9ebc0388ee4e45 Mon Sep 17 00:00:00 2001 From: Patrick Spek Date: Sun, 17 Apr 2022 22:26:45 +0200 Subject: Update the README to be about Bashtard --- README.md | 160 +++++++++++++++++++++++--------------------------------------- 1 file changed, 59 insertions(+), 101 deletions(-) diff --git a/README.md b/README.md index d6c83dc..de05c71 100644 --- a/README.md +++ b/README.md @@ -1,132 +1,90 @@ -# tyil.net +# Bashtard -The collection of servers and clients in Tyil's network. +Bashtard is a small configuration management system written in Bash. -## Architecture +## Getting Started -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. +Since Bashtard is written in bash, you will need to have Bash available in your +`$PATH`. You will also need to have a POSIX compatible system, and the +associated utilities installed and available in your `$PATH`. Lastly, to keep +your setup synchronized, `git` is used. -### Network Layout +Once you have everything installed, Bashtard itself can be installed using the +provided `Makefile`. -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. + make install -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 +### Bootstrapping -## Bootstrap +When Bashtard is installed, the next step is bootstrapping the system. The +`bootstrap` subcommand will perform all necesary steps to create the desired +structure in `/etc/bashtard`. -Ensure you have a POSIX-compliant system, with `bash` and `git` available in -your `$PATH` as well. + bashtard bootstrap - # Clone the repository - git clone https://git.tyil.nl/tyilnet /usr/tyilnet +It is recommended you create a `git` directory out of `/etc/bashtard` for +synchronization purposes. This will allow you to bootstrap Bashtard on other +systems by giving it the URL of the git repository as additional argument. - # Bootstrap the main application - /usr/tyilnet/bin/tyilnet bootstrap + bashtard bootstrap https://git.tyil.nl/tyilnet.git -The bootstrap command will also configure a cronjob to run `tyilnet sync` every -2 hours. +With the additional argument, it will clone the repository to `/etc/bashtard`, +and then apply any additional steps for the machine you're bootstrapping. -## Set +## General Usage -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. +After bootstrapping, you can start using Bashtard. It has the concept of +playbooks, which can either be local or cloned from a remote git repository. -## SSH +### One-off updates -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. +To perform updates once by hand, use the `sync` subcommand. - tyilnet ssh + `bashtard sync` -## Services +This will pull the latest changes of remote playbooks, and then run a `sync` +command for each playbook that is used on the machine. -### Backup +### Regular updates -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. +If you want to do updates on a regular basis, you should configure your +preferred cron system to do so. - tyilnet backup/bootstrap +### Playbooks -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`. +These are the essential components for doing the actual work. Playbooks are +directories with a `description.txt` and a `playbook.bash`. The latter contains +3 functions, `playbook_add()`, `playbook_sync()`, and `playbook_del()`, each +called for the `add`, `sync`, end `del` subactions respectively. Using these +functions, one can automate the setup, synchronization, or disabling of certain +components of a system. - tyilnet set borg.key.$FQDN.hostfs +#### Local -If the machine is also hosting databases, encryption keys for those may need to -be set too. +A local playbook is simply a directory made in `/etc/bashtard/playbooks.d` with +the two files specified earlier. -Once preconfiguration is done, you can run the actual backups using the -`backup` command. +#### Remote - tyilnet backup +A remote playbook is recorded in `/etc/bashtard/playbooks.d/remotes`. This is a +space-seperated file, containing 3 columns per line, `name`, `url`, and +`branch`. When the `sync` subcommand is called, the latest commits on the +specified `branch` are pulled before calling `playbook_sync()` on them. The +structure of the actual playbook is the same as a local one. -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. +### SSH -### Metrics +Bashtard comes with an `ssh` subcommand to allow the user to run any command on +all their servers. This can be useful for performing certain actions on all your +servers at once. -Every node in the network should export metrics for use by Prometheus. This -action will set this up. +## Debugging and Support - tyilnet metrics/bootstrap +For support you can email to `~tyil/bashtard@lists.sr.ht`. If you're reporting a +bug, it is recommended to include a reproduction path which is as clear as +possible. Additionally, you should include the output of the `sysinfo` +subcommand. -### Metrics Server +## License -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. +This project is licensed under the terms of the AGPL-3.0. -- cgit v1.1