iiab/roles/0-init/tasks/validate_vars.yml

# 2020-01-21: Ansible Input Validation (basic sanity checking for now) to check
# that *_install and *_enabled variables (as set in places like
# /etc/iiab/local_vars.yml) appear coherent i.e. (1) are confirmed defined,
# (2) have type boolean (Ansible often inverts logic when boolean vars are
# accidentally declared as strings, see below!) and (3) have plausible values.

# 2020-01-23: *_installed variables (incrementally saved to
# /etc/iiab/iiab_state.yml) are not required to be boolean (or even defined!)
# for now.  However if any of these are defined, the corresponding value of
# *_install must be True, as IIAB does not currently support uninstalling!

# Stricter validation is needed later, when roles/playbooks/tasks are invoked
# by various scripts, possibly bypassing 0-init?  Either way, risks abound :/

# 1. "Ansible 2.8+ ADVISORY: avoid warnings by using 'when: var | bool' for
# top-level BARE vars (in case they're strings, instead of boolean)" per #1632.
# 2020-10-16: NO LONGER NEC, SEE: https://github.com/iiab/iiab/pull/2576

# 2. "How Exactly Does Ansible Parse Boolean Variables?"
# https://stackoverflow.com/questions/47877464/how-exactly-does-ansible-parse-boolean-variables/47877502#47877502
# ...is very helpful but has it slightly wrong, as Ansible implements only ~18
# of YAML's 22 definitions of boolean (https://yaml.org/type/bool.html).
# i.e. Ansible fails to implement y|Y|n|N, only allowing ~18 boolean values:
#
# yes|Yes|YES|no|No|NO
# |true|True|TRUE|false|False|FALSE
# |on|On|ON|off|Off|OFF
#
# Otherwise 'var != (var | bool)' is dangerously common, e.g. (1) when a var
# is not one of the above ~18 words (forcing it to become a string) or (2) when
# a var is accidentally set using quotes (forcing it to become a string) these
# ~18 words too WILL FAIL as strings (as will any non-empty string...so beware
# casting strings to boolean later on...can make the situation worse!)
# https://docs.ansible.com/ansible/latest/porting_guides/porting_guide_2.8.html#bare-variables-in-conditionals
#
# 2020-07-08 - Excellent analysis & summary by Jon Spriggs: "In Ansible,
# determine the type of a value, and casting those values to other types"
# https://jon.sprig.gs/blog/post/1801
#
# 2021-01-29 - ansible-base 2.10.5 (1) is more strict about empty string vars
# (2) no longer supports "when: myvar is boolean", "is integer" & "is float"
# (3) brings yet more "Ansible Collections" dependency changes (undocumented!)
# Details: https://github.com/iiab/iiab/pull/2672 (see also #2669)

# 3. "How do i fail a task in Ansible if the variable contains a boolean value?
# I want to perform input validation for Ansible playbooks"
# https://stackoverflow.com/questions/46664127/how-do-i-fail-a-task-in-ansible-if-the-variable-contains-a-boolean-value-i-want/46667499#46667499

# 2020-01-23: Checks 53 + 53 + up-to-53 vars...for now...expect this to change!
# 2020-09-26: Commented out 14 vars that are {mandatory, dependencies, or
# unmaintained-for-years} for IIAB 7.2 release.  Keeping in mind that vars
# will come and go as IIAB evolves, let's try to keep these 9 aligned:
#
# http://FAQ.IIAB.IO > "What services (IIAB apps) are suggested during installation?"
# https://github.com/iiab/iiab/blob/master/vars/local_vars_min.yml
# https://github.com/iiab/iiab/blob/master/vars/local_vars_medium.yml
# https://github.com/iiab/iiab/blob/master/vars/local_vars_big.yml
# https://github.com/iiab/iiab/blob/master/vars/default_vars.yml
# https://github.com/iiab/iiab/blob/master/unmaintained-roles.txt
# https://github.com/iiab/iiab/blob/master/roles/0-DEPRECATED-ROLES/
# https://github.com/iiab/iiab/blob/master/tests/test.yml
# https://github.com/iiab/iiab/blob/master/roles/0-init/tasks/validate_vars.yml
#
# 2020-11-04: Fix validation of 5 [now 4] core dependencies, for ./runrole etc

- name: Set vars_checklist for 44 + 44 + 40 vars ("XYZ_install" + "XYZ_enabled" + "XYZ_installed") to be checked
  set_fact:
    vars_checklist:
      - hostapd
      - dhcpd
      - named
      - dnsmasq
      - bluetooth
      #- wondershaper       # Unmaintained
      - sshd
      - openvpn
      - admin_console
      #- nginx              # MANDATORY
      #- apache             # Unmaintained - former dependency
      #- mysql              # MANDATORY
      - squid
      - dansguardian
      - cups
      - samba
      - usb_lib
      #- xo_services        # Unmaintained
      #- activity_server    # Unmaintained
      #- ejabberd_xs        # Unmaintained
      #- idmgr              # Unmaintained
      - azuracast
      #- dokuwiki           # Unmaintained
      #- ejabberd           # Unmaintained
      #- elgg               # Unmaintained
      - gitea
      - jupyterhub
      - lokole
      - mediawiki
      - mosquitto
      - nodejs              # Dependency - excluded from _installed check below
      - nodered
      - nextcloud
      - wordpress
      - kalite
      - kolibri
      - kiwix
      - postgresql          # Dependency - excluded from _installed check below
      - moodle
      - mongodb             # Dependency - excluded from _installed check below
      - sugarizer
      - osm_vector_maps
      - transmission
      - awstats
      - monit
      - munin
      - phpmyadmin
      - vnstat
      - yarn                # Dependency - excluded from _installed check below
      - captiveportal
      - internetarchive
      - minetest
      - calibreweb
      - calibre
      - pbx

- name: Assert that {{ vars_checklist | length }} "XYZ_install" vars are all... defined
  assert:
    that: "{{ item }}_install is defined"
    fail_msg: "VARIABLE MUST BE DEFINED: '{{ item }}_install' NEEDS A PROPER (UNQUOTED) ANSIBLE BOOLEAN VALUE e.g. IN: /etc/iiab/local_vars.yml"
    quiet: yes
  loop: "{{ vars_checklist }}"

- name: Assert that {{ vars_checklist | length }} "XYZ_enabled" vars are all... defined
  assert:
    that: "{{ item }}_enabled is defined"
    fail_msg: "VARIABLE MUST BE DEFINED: '{{ item }}_enabled' NEEDS A PROPER (UNQUOTED) ANSIBLE BOOLEAN VALUE e.g. IN: /etc/iiab/local_vars.yml"
    quiet: yes
  loop: "{{ vars_checklist }}"

- name: Assert that {{ vars_checklist | length }} "XYZ_install" vars are all... type boolean (NOT type string, which can invert logic!)
  assert:
    that: "{{ item }}_install | type_debug == 'bool'"
    fail_msg: "VARIABLE MUST BE BOOLEAN: '{{ item }}_install' now has type '{{ lookup('vars', item + '_install') | type_debug }}' and value '{{ lookup('vars', item + '_install') }}' -- PLEASE SET A PROPER (UNQUOTED) ANSIBLE BOOLEAN VALUE e.g. IN: /etc/iiab/local_vars.yml"
    quiet: yes
  loop: "{{ vars_checklist }}"

- name: Assert that {{ vars_checklist | length }} "XYZ_enabled" vars are all... type boolean (NOT type string, which can invert logic!)
  assert:
    that: "{{ item }}_enabled | type_debug == 'bool'"
    fail_msg: "VARIABLE MUST BE BOOLEAN: '{{ item }}_enabled' now has type '{{ lookup('vars', item + '_enabled') | type_debug }}' and value '{{ lookup('vars', item + '_enabled') }}' -- PLEASE SET A PROPER (UNQUOTED) ANSIBLE BOOLEAN VALUE e.g. IN: /etc/iiab/local_vars.yml"
    quiet: yes
  loop: "{{ vars_checklist }}"

- name: 'DISALLOW "XYZ_install: False" WITH "XYZ_enabled: True" ...for all {{ vars_checklist | length }} var pairs'
  assert:
    that: "{{ item }}_install or not {{ item }}_enabled"
    fail_msg: "DISALLOWED: '{{ item }}_install: False' WITH '{{ item }}_enabled: True' -- IIAB DOES NOT SUPPORT UNINSTALLS -- please verify those 2 variable values e.g. in /etc/iiab/local_vars.yml, and other places variables are defined?"
    quiet: yes
  loop: "{{ vars_checklist }}"

- name: 'DISALLOW "XYZ_install: False" WHEN "XYZ_installed is defined" IN /etc/iiab/iiab_state.yml ...for up-to-{{ vars_checklist | length }} var pairs'
  assert:
    that: "{{ item }}_install or {{ item }}_installed is undefined"
    fail_msg: "DISALLOWED: '{{ item }}_install: False' (e.g. in /etc/iiab/local_vars.yml) WHEN '{{ item }}_installed' is defined (e.g. in /etc/iiab/iiab_state.yml) -- IIAB DOES NOT SUPPORT UNINSTALLS -- please verify those 2 files especially, and other places variables are defined?"
    quiet: yes
  when: item != 'nodejs' and item != 'postgresql' and item != 'mongodb' and item != 'yarn'    # Exclude auto-installed dependencies
  loop: "{{ vars_checklist }}"