path: root/README.md
diff options
authorPatrick Spek <p.spek@tyil.nl>2022-04-17 22:26:45 +0200
committerPatrick Spek <p.spek@tyil.nl>2022-04-17 22:26:45 +0200
commite281eedb6f6e0fda791a45145f9ebc0388ee4e45 (patch)
tree139930bcf811a57bba2cf2411ac6f37f341282b1 /README.md
parentad62d1da67831c6de287835a1188cead7c3f4ff1 (diff)
Update the README to be about Bashtard
Diffstat (limited to 'README.md')
1 files 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 `` for IPv4, and `fd14:199c:e514::/48` for
-IPv6. These are then divided in specific categories.
+ make install
-Category | IPv4 Range | IPv6 Range
-Workstations | | fd14:199c:e514:1::/64
-Servers | | 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 <command>
+ `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 <encryption-key>
+#### 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
+### 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`
-### 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.