diff --git a/README.md b/README.md index 0905bb5..00f86e2 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,3 @@ # 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. - - - - +Automates the implementation of VPS servers for my server ecosystem. There is a specific logic and structure to this project, that will be expounded on herein.