sukaato-ansible/README.md

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:

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:

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.