README.md

# rbfsmi-ansible

## How these ansible playbooks are applied

The ansible-pull role uses ansible's "ansible-pull" feature to
regularly clone a git repo (see ansible-pull.service/timer) and apply
the contained changes to the local host via the local.yml playbook.
This yields eventually consistent, centrally managed state on each
host and eliminates the need for a central server (like awx) that
pushes ansible onto each host.

Usually ansible is used in a "push" model, where you define an
inventory, consisting of hosts and groups, and apply the playbook
to the remote inventory.
Ansible-pull, however, assumes a single host, "localhost", and therefore
omits reading the inventory and groups.

To get the groups you'd have in a conventional inventory file to work
correctly, at the start of local.yml the groups are read from the
hosts' host_vars files.
The groups are specified in the `pull_groups` array.

Still, ansible-pull assumes one host and the variables for the other
hosts, that you would usually find in the `hostvars` array, are not
available.
For this a dynamic inventory script is used that reads the hosts'
host_vars files and returns the host list to ansible-pull.
Its location has to be passed to ansible per `-i` argument.

Thus, we recommend that you develop (and test) your changes via the
following ansible command. Note that you will need to be able to ssh
into the host's root account.

`ansible-playbook -i inventory local.yml --diff --limit pocket-coffee`

Please note that there are certain elements that are (currently) not
100% automated yet; these are annotated with `MANUAL` where
appropriate, and indicate some additional action you need to take
after installation.

For a few pointers to ansible documentation, take a look at the end of this
README.

## Additional commands

To use an ssh jump host add the following argument:

`--ssh-common-args '-o ProxyJump=JUMPHOSTNAME'`

When applying the playbook to the localhost add:

`--connection=local`

## How to install a host

0. Apply the firmware settings (see below) in the UEFI menu
1. Boot Arch Linux Live / Installation ISO
   - [Download](https://www.archlinux.org/download/) the ISO
   - [Verify](https://wiki.archlinux.org/index.php/Installation_guide#Verify_signature) the PGP signature, e.g. using `pacman-key -v archlinux-*-x86_64.iso.sig` on Arch Linux (signature probably from Pierre Schmitz' key 4AA4 767B BC9C 4B1D 18AE  28B7 7F2D 434B 9741 E8AC)
   - if VM:
     - boot in EFI mode; see [Arch Linux's libvirt docs](https://wiki.archlinux.org/index.php/Libvirt#UEFI_Support)
     - manually add an IP address, a route and a nameserver for network access
2. In the live system:
   - `curl -O 'https://git.cs.uni-paderborn.de/rbfsmi/rbfsmi-ansible/-/raw/master/bootstrap.sh'`
   - `chmod +x bootstrap.sh`
   - `./bootstrap.sh [--irb-vm] --hostname $CAFFEINE_BASED_HOSTNAME` (see `--help` for details)
3. (Host installs, reboots, and does an initial ansible-pull)
4. Wait until ansible-pull.service has finished running. (takes ~3 min)
5. …
6. Profit.


## Firmware settings needed

### Mini PC
For the ZOTAC mini PCs (muckefuck, pocket-coffee):

DTS Sensors: on  
VT-D: on  
Network Stack: on

### Big PC
For the Desktop PCs:

ADV > CPU > SVM > Enabled  
ADV > Onboard > LED > Still


## Ansible documentation
Ansible's documentation can be a bit convoluted, so here are some pointers to
possibly relevant (sub)pages:

 * general [User Guide](https://docs.ansible.com/ansible/latest/user_guide/)
 * [Module Index](https://docs.ansible.com/ansible/latest/collections/index_module.html#ansible-builtin)!
 * [Playbook Keywords](https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html)
 * Templates (using variables etc.):
   * [Filters](https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html)
   * [Jinja Templates](https://jinja.palletsprojects.com/templates/#sidebar-top)


## License
The files in this repository are licensed under the MIT license unless
otherwise declared. See the file LICENSE for details.