From d4432cb0f48a3ceff1ea77a6bae3ce3d33a97e08 Mon Sep 17 00:00:00 2001 From: Gregor Michels Date: Sun, 3 Jul 2022 02:41:50 +0200 Subject: [PATCH] cleanup README --- README.md | 107 +++++++++++++++++++++++------------------------------- 1 file changed, 45 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index b14ed5f..da17371 100644 --- a/README.md +++ b/README.md @@ -4,72 +4,55 @@ This repo contains the config and documentation for our installation at the "Ers --- -**more documentation / information will follow** +**this is a work in progress** --- -## Admin Guide - -requirements: -* `ansible` -* `pandoc` (for offline documentation generation) -* `pass` - -### Password Manager - -1. import all gpg keys (only on first use or new admin - all keys need to be trusted - use `--edit-key` to edit the trust level): -``` -user@freifunk-admin:~/ffl-eae-adp/files/gpg$ gpg --import * -gpg: key F937CB4882C16136: "hirnpfirsich@ffl-eae-adp-password" not changed -gpg: key 2438B8ADFDF45447: 1 signature not checked due to a missing key -gpg: key 2438B8ADFDF45447: "Alexander Böhm " not changed -gpg: Total number processed: 2 -gpg: unchanged: 2 -user@freifunk-admin:~/ffl-eae-adp/files/gpg$ -``` -2. source environment (on every new shell): -``` -user@freifunk-admin:~/ffl-eae-adp$ . environment -``` -3. use :) -``` -user@freifunk-admin:~/ffl-eae-adp$ pass -Password Store -├── accesspoints -│   ├── ap-0b99 -│   ├── ap-1a38 -│   ├── ap-2bbf -│   ├── ap-8f39 -[...] -user@freifunk-admin:~/ffl-eae-adp -``` - -### SSH - -use `playbook_create_ssh_config.yml` to generate an `ssh_config` file that gets linked into your `ssh_config`. -optionally specify a jumphost (ie. `eae-adp-jump01`) - -``` -user@freifunk-admin:~/ffl-eae-adp$ ansible-playbook -e jumphost=eae-adp-jump01 playbook_create_ssh_config.yml - -PLAY [generate ssh_config] ****************************************************************************************************************************************************************************************************** - -TASK [generate ssh_config file] ************************************************************************************************************************************************************************************************* -changed: [localhost] - -TASK [include custom ssh_config] ************************************************************************************************************************************************************************************************ -ok: [localhost] - -PLAY RECAP ********************************************************************************************************************************************************************************************************************** -localhost : ok=2 changed=1 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - -user@freifunk-admin:~/ffl-eae-adp$ ssh gw-core01 uptime - 23:54:52 up 6:49, load average: 0.05, 0.01, 0.00 -user@freifunk-admin:~/ffl-eae-adp$ -``` - -## Links +## Quick Links * [Documentation](documentation/README.md) * [Incidents](documentation/INCIDENTS.md) * [TODO](documentation/TODO.md) + +## Usage + +### Requirements + +* `pass` (password manager) +* `pandoc` (offline documentation generation) +* `python3` (ansible) +* `python3-venv` (ansible) +* `rsync` (ansible) + +### Initial Setup + +0. install requirements +1. clone repo and change directory: `git clone https://git.sr.ht/~hirnpfirsich/ffl-eae-adp && cd ffl-aea-adp` +2. create python3 virtual enviroment: `python3 -m venv ansible-environment` +3. enter python3 virtual environment: `. ansible-environment/bin/activate` +4. install ansible and dependencies: `pip3 install -r ansible-environment.txt` +5. import all gpg keys for `pass`: `gpg --import files/gpg/*` +6. trust all imported gpg keys: `gpg --edit-key ` with `trust` and `5` for every key +7. create `ssh_config` with all hosts: `ansible-playbook playbook_create_ssh_config.yml` (use `-e jumphost=eae-adp-jump01` to configure ssh to use `eae-adp-jump01` as the jump host) +8. leave python3 virtual environment: `deactivate` + +### Daily Usage + +Before doing enything you need to enter the environment: `. environment` + +After using `playbook_create_ssh_config.yml` you can call `ssh` simply with the name of the machine (ie. `ssh gw-core01`). +The `ssh_config` file is generated from the `ansible-inventory`. +Should something in the inventory change or you want to use/change the jumphost simply reexecute the playbook. + +Passwords managed using `pass`. Simply call `pass` after sourcing the environment. + +### Descriptions + +* `environment`: configure environment (path to `pass` store, http(s) socks proxy and python venv for ansible) +* `playbook_create_ssh_config.yml`: playbook to create an additional `ssh_config` file (`.ssh/ffl_eae_adp_config`) that get's included in the default `ssh_config` +* `playbook_distribute_authorized_keys.yml`: deploy `files/authorized_keys` on all machines +* `playbook_provision_accesspoints.yml`: configure accesspoints +* `playbook_provision_backbone.yml`: configure wg tunnel and ospf link between `gw-core01` and `eae-adp-jump01` +* `playbook_provision_eap-adp-jump01.yml`: general system configuration for `eae-adp-jump01` (monitoring, routing, ...) +* `playbook_provision_hyper01.yml`: general system configuration for `hyper01` and create vms/containers +* `playbook_provision_monitoring.yml`: configure and install prometheus and grafana on `monitoring01`