From b566daed4482e9349d4e47e7edcaa971a2bb506f Mon Sep 17 00:00:00 2001 From: Alex Tavarez Date: Tue, 22 Jul 2025 10:24:22 -0400 Subject: [PATCH] Added some documentation for Ansible herein --- README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/README.md b/README.md index e69de29..0905bb5 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,66 @@ +# SUKAATO Ansible + +Automates the implementation of VPS servers for the SUKAATO web domain ecosystem. There is a specific logic and structure to this project, that will be expounded on herein. + +## Default Groups + +The default inventory groups and their child groups in this Ansible project are: +- `vps`, for virtual private servers + - `web`, for webservers + - `mail`, for email servers if separate +- `local`, for LAN servers + - `stationary` + - `mobile` +- `this`, for localhost servers + +## Assumed Host and Group Variables + +Inventory group variables should be placed in files or directories under `group_vars/` that have the associated group name as filename or directory name, and inventory host variables should be placed in files or directories under `host_vars/` that have the associated hostname or fully qualified domain name as filename or directory name. + +More importantly, the following variables should be specified for groups or hosts: +- `hname`: The hostname to be placed in `/etc/hosts` for the target server(s) +- `tzone`: The timezone for the target server(s) +- `remote`: Specifies the host or group of hosts are at public address rather than at loopback address +- `root_auths`: A list of accounts with their authentication that are or are to be root on the target server (more details on this later) +- `admin_auths`: A list of accounts with their authentication that have or are to have superuser privileges on the target server +- `guest_auths`: A list of accounts that are or are to be guest accounts +- `user_auths`: A list of accounts with their authentication that are or are to be standard/regular user accounts +- `regular_accts`: A list combination of the last 3 list type variables--do not change this variable unless you know what you're doing +- `user_pubkeys`: A list structured around the specific SSH keys for accounts under `regular_accts` +- `crowdsec_key`: The enrollment key for initial set-up of crowdsec security engine; gotten from a CrowdSec online account +- `gocrypt_password`: The password for or to be set for any and all gocryptfs vaults + +Because Crowdsec is installed by playbook `install@vps.yml` by default, `crowdsec_key` is also required among these. In addition, `gocrypt_password` is required as part of importing private GPG keys during the `configure@vps.yml` playbook run. This is because the GPG private key file is held inside a `gocryptfs` vault in the target server rather than deleted after import. (To disable this, edit `roles/bootstrap/tasks/configure_core/gpg.yml` appropriately.) + +For all aforementioned host or group variables that are account lists, as well as for `gocrypt_password` and `crowdsec_key`, it is recommended to create directories for groups and hosts that contain their variables in a file under that directory--a file called `vars`. That way, a `vault` file sharing the same parent directory can be used for storing and encrypting that sensitive authentication and user information that is then referenced by `vars`. + +The items in each account list represent users and have a particular syntax, exemplified by the following: + +```yaml +username: ~ +actual_name: ~ +password: ~ +email: ~ +ssh_auth: ~ +``` + +The `ssh_auth` field for the user is itself a list of public SSH keys for that user. + +## Custom Package Installations + +To install additional packages than core packages, first make sure that `install@vps.yml` playbook has playbook variable `want_extra_pkgs` set to `yes`, then edit the file at `roles/bootstrap/defaults/custom_pkgs@Debian.yml`. In that file, the syntax requires that the packages be listed under the YAML field `my_pkgs`, and it also requires that each element in the list have a `package` field while optionally a `version` field. An example of such an element would be: + +```yaml +package: inspircd +version: ~ +``` + +## Dynamic Playbook Variables, Role Variables and Role Defaults + +By default, variables referenced in role tasks and role handlers--unless Ansible "magic variables" or group/host variables--are also listed as role defaults, in a file `general.yml` under the `main` subdirectory for defaults. This is to make the use of yet-undeclared variables in the role more transparent. Typically, such variables not declared or assigned in the role itself, though referenced by it, are dynamically assigned or declared within playbooks. + +For ease, you may prefer to simply copy-paste the variables defined in `${ROLE}/defaults/main/general.yml` of the relevant role into some file in that role's `vars` directory--likely `main.yml`. Then, in the applicable playbooks, under role inclusions in tasks you can add a `vars_from` field entry. + + + +