Merge pull request #2158 from holta/cleanups

Cleanup of NGINX/Apache log file PRs #2155, #2156 & begin streamlining Munin playbook (WIP)

roles/2-common/tasks/fl.yml

@@ -1,26 +1,28 @@
 # fl.yml signifies "file layout"
 
-- name: Create directories with ownership root:root and permissions 0755 (1 in /etc, 1 in {{ py3_dist_path }}, 3 in {{ iiab_base }} and 15 in /library)    # py3_dist_path is /usr/lib/python3/dist-packages, iiab_base is /opt/iiab
+- name: "File Layout - Create directories: 1 in /etc, 1 in {{ py3_dist_path }}, 2 in {{ iiab_base }}, 15 in {{ content_base }}"    # iiab_base: /opt/iiab
   file:
     path: "{{ item }}"
-    owner: root
-    group: root
-    mode: 0755
+    # owner: root
+    # group: root
+    # mode: '0755'
     state: directory
   with_items:
     - /etc/sysconfig/olpc-scripts/setup.d/installed/
-    - "{{ yum_packages_dir }}"
-    - "{{ pip_packages_dir }}"
-    - "{{ downloads_dir }}"
-    - /library/downloads/zims
-    - /library/downloads/rachel
-    - /library/downloads/maps
-    - /library/working/zims
-    - /library/working/rachel
-    - /library/working/maps
-    - "{{ iiab_zim_path }}/content"
+    - "{{ py3_dist_path }}/iiab"    # /usr/lib/python3/dist-packages
+    - "{{ yum_packages_dir }}"    # /opt/iiab/yum-packages
+    - "{{ pip_packages_dir }}"    # /opt/iiab/pip-packages
+    #- "{{ downloads_dir }}"    # /library/downloads auto-created just below
+    - "{{ downloads_dir }}/zims"
+    - "{{ downloads_dir }}/maps"
+    #- "{{ downloads_dir }}/rachel"
+    #- "{{ content_base }}/working"     # /library/working auto-created just below
+    - "{{ content_base }}/working/zims"
+    - "{{ content_base }}/working/maps"
+    #- "{{ content_base }}/library/working/rachel"
+    - "{{ iiab_zim_path }}/content"     # /library/zims
     - "{{ iiab_zim_path }}/index"
-    - "{{ doc_root }}/local_content"
+    - "{{ doc_root }}/local_content"    # /library/www/html
     - "{{ doc_root }}/modules"
     - "{{ doc_root }}/common/css"
     - "{{ doc_root }}/common/js"
@@ -29,10 +31,20 @@
     - "{{ doc_root }}/common/images"
     - "{{ doc_root }}/common/assets"
     - "{{ doc_root }}/common/services"
-    - "{{ py3_dist_path }}/iiab"
 
-- name: Symlink from {{ doc_root }}/common/webfonts to {{ doc_root }}/common/fonts
+- name: File Layout - Symlink {{ doc_root }}/common/webfonts -> {{ doc_root }}/common/fonts
   file:
-    src: "{{ doc_root }}/common/fonts"
+    src: "{{ doc_root }}/common/fonts"    # /library/www/html
     path: "{{ doc_root }}/common/webfonts"
     state: link
+
+- name: File Layout - Create log file directories {{ apache_log_dir }} & {{ nginx_log_dir }}
+  file:
+    path: "{{ item }}"
+    owner: "{{ apache_user }}"    # www-data
+    group: "{{ apache_user }}"    # www-data
+    mode: '0770'
+    state: directory
+  with_items:
+    - "{{ apache_log_dir }}"    # /var/log/apache2 typically, as set in /opt/iiab/iiab/vars/<OS>.yml
+    - "{{ nginx_log_dir }}"     # /var/log/nginx

roles/9-local-addons/tasks/main.yml

@@ -11,7 +11,9 @@
 
 # Is porting to Python 3 complete, and if so does this belong elsewhere?
 - name: CAPTIVE PORTAL
-  include_tasks: roles/captiveportal/tasks/main.yml
+  include_role:
+    name: captiveportal
+  #include_tasks: roles/captiveportal/tasks/main.yml
   when: captiveportal_install | bool
   #tags: base, captiveportal, network, domain
 

roles/awstats/templates/awstats.schoolserver.conf.j2

@@ -48,11 +48,12 @@
 # Example: "/pathtotools/logresolvemerge.pl *.log |"
 #
 
-{% if is_debuntu %}
-LogFile="/usr/share/awstats/tools/logresolvemerge.pl {{ apache_log_dir }}/access.log* |"
-{% else %}
-LogFile="/usr/share/awstats/tools/logresolvemerge.pl /var/log/httpd/access_log* |"
-{% endif %}
+LogFile="/usr/share/awstats/tools/logresolvemerge.pl {{ nginx_log_dir }}/access.log* |"
+#{% if is_debuntu %}
+#LogFile="/usr/share/awstats/tools/logresolvemerge.pl {{ nginx_log_dir }}/access.log* |"
+#{% else %}
+#LogFile="/usr/share/awstats/tools/logresolvemerge.pl {{ nginx_log_dir }}/access_log* |"
+#{% endif %}
 
 # Enter the log file type you want to analyze.
 # Possible values:

roles/captiveportal/tasks/main.yml

@@ -1,4 +1,6 @@
-- name: Download & install python-dateutil, sqlite3
+# TO DO: move ~7 stanzas below into tasks/install.yml
+
+- name: "Download & install packages: python3-dateutil, python3-jinja2"
   package:
     name: "{{ item }}"
     state: present
@@ -6,94 +8,102 @@
     - python3-dateutil
     - python3-jinja2
 
-- name: Create directory /opt/iiab/captiveportal for scripts & templates
+- name: Create directory /opt/iiab/captiveportal for scripts & templates; set owner to {{ apache_user }}
   file:
     path: /opt/iiab/captiveportal
     state: directory
     owner: "{{ apache_user }}"
 
-- name: 'Copy scripts: checkurls'
+- name: "Install 3 scripts from template: /opt/iiab/captiveportal/checkurls, /usr/sbin/iiab-make-cp-servers.py, /usr/sbin/iiab-divert-to-nginx"
   template:
     src: "{{ item.src }}"
     dest: "{{ item.dest }}"
     mode: "{{ item.mode }}"
   with_items:
-    - { src: roles/captiveportal/templates/checkurls, mode: '0644', dest: /opt/iiab/captiveportal/ }
-    - { src: roles/captiveportal/templates/iiab-make-cp-servers.py, mode: '0755', dest: /usr/sbin/ }
-    - { src: roles/captiveportal/templates/iiab-divert-to-nginx, mode: '0755', dest: /usr/sbin/ }
+    - { src: roles/captiveportal/templates/checkurls, dest: /opt/iiab/captiveportal/, mode: '0644' }
+    - { src: roles/captiveportal/templates/iiab-make-cp-servers.py, dest: /usr/sbin/, mode: '0755' }
+    - { src: roles/captiveportal/templates/iiab-divert-to-nginx, dest: /usr/sbin/, mode: '0755' }
 
-- name: Put put the python script that creates the server in place
+- name: Install /opt/iiab/captiveportal/capture-wsgi.py from template (creates the server)
   template:
-    src: roles/captiveportal/templates/capture-wsgi.py 
-    mode: '0755' 
-    dest: /opt/iiab/captiveportal/ 
+    src: capture-wsgi.py.j2
+    #src: roles/captiveportal/templates/capture-wsgi.py.j2
+    dest: /opt/iiab/captiveportal/capture-wsgi.py
+    mode: '0755'
 
-- name: 'Copy templates: simple.template, mac.template'
+- name: Copy files {simple.template, mac.template} into /opt/iiab/captiveportal/
   copy:
     src: "{{ item }}"
     dest: /opt/iiab/captiveportal/
   with_items:
-    - roles/captiveportal/files/simple.template
-    - roles/captiveportal/files/mac.template
+    - simple.template
+    #- roles/captiveportal/files/simple.template
+    - mac.template
+    #- roles/captiveportal/files/mac.template
 
-- name: Copy uWSGI config file
+- name: Install uWSGI config file /opt/iiab/captiveportal/captiveportal.ini from template
   template:
-    src: roles/captiveportal/templates/captiveportal.ini.j2
+    src: captiveportal.ini.j2
+    #src: roles/captiveportal/templates/captiveportal.ini.j2
     dest: /opt/iiab/captiveportal/captiveportal.ini
 
-- name: Copy unit file for uWSGI service
-  template:
-    src: roles/captiveportal/templates/uwsgi-captiveportal.service
-    dest: /etc/systemd/system/
-
-- name: Start or restart server which responds to browsers trying to detect a captive portal
-  systemd: 
-    name: uwsgi-captiveportal.service
-    state: restarted
-    enabled: True
-  when: captiveportal_enabled | bool
-
-- name: Stop uWSGI server if captive portal has been disabled
-  systemd: 
-    name: uwsgi-captiveportal.service
-    state: stopped
-    enabled: False
-  when: not captiveportal_enabled | bool
-
-- name: Run divert to generate diversion lists for nginx
-  shell: /usr/sbin/iiab-divert-to-nginx
-     
-- name: Run script to generate nginx servers from checkurls input list
-  command: /usr/sbin/iiab-make-cp-servers.py
-  args:
-      creates: /etc/nginx/sites-available/capture.conf
-  
-- name: Enable nginx to service the sites in checkurls list
-  file:
-    src: /etc/nginx/sites-available/capture.conf
-    path: /etc/nginx/sites-enabled/capture.conf
-    state: link
-  when: captiveportal_enabled | bool
-
-- name: Disable nginx to location definitions for checkurls
-  file:
-    src: /etc/nginx/sites-available/capture.conf
-    path: /etc/nginx/sites-enabled/capture.conf
-    state: absent
-  when: not captiveportal_enabled | bool
-
-- name: Make sure dnsmasq is not diverting if not captiveportal_enabled
-  file:
-    path: /etc/dnsmasq.d/capture
-    state: absent
-  when: not captiveportal_enabled
-
 - name: "Add 'captiveportal_installed: True' to {{ iiab_state_file }}"
   lineinfile:
     dest: "{{ iiab_state_file }}"    # /etc/iiab/iiab_state.yml
     regexp: '^captiveportal_installed'
     line: 'captiveportal_installed: True'
 
+# TO DO: move most/all 7-10 stanzas below into enable-or-disable.yml
+
+- name: Install /etc/systemd/system/uwsgi-captiveportal.service from template
+  template:
+    src: uwsgi-captiveportal.service
+    #src: roles/captiveportal/templates/uwsgi-captiveportal.service
+    dest: /etc/systemd/system/
+
+- name: Restart & Enable 'uwsgi-captiveportal' systemd service (uWSGI server) that responds to browsers trying to detect a Captive Portal
+  systemd:
+    name: uwsgi-captiveportal
+    daemon_reload: yes
+    state: restarted
+    enabled: True
+  when: captiveportal_enabled | bool
+
+- name: Stop & Disable 'uwsgi-captiveportal' systemd service (uWSGI server) if Captive Portal has been disabled
+  systemd:
+    name: uwsgi-captiveportal
+    state: stopped
+    enabled: False
+  when: not captiveportal_enabled
+
+- name: Run iiab-divert-to-nginx to generate diversion lists for NGINX
+  shell: /usr/sbin/iiab-divert-to-nginx
+
+- name: Run iiab-make-cp-servers.py to generate NGINX servers from checkurls input list (creates /etc/nginx/sites-available/capture.conf)
+  command: /usr/sbin/iiab-make-cp-servers.py
+  args:
+    creates: /etc/nginx/sites-available/capture.conf
+
+- name: Symlink /etc/nginx/sites-enabled/capture.conf -> /etc/nginx/sites-available/capture.conf, to enable NGINX to service the sites in checkurls list
+  file:
+    src: /etc/nginx/sites-available/capture.conf
+    path: /etc/nginx/sites-enabled/capture.conf
+    state: link
+  when: captiveportal_enabled | bool
+
+- name: Delete symlink /etc/nginx/sites-enabled/capture.conf, to disable NGINX to location definitions for checkurls
+  file:
+    #src: /etc/nginx/sites-available/capture.conf
+    path: /etc/nginx/sites-enabled/capture.conf
+    state: absent
+  when: not captiveportal_enabled
+
+- name: Make sure dnsmasq is not diverting if not captiveportal_enabled
+  file:
+    path: /etc/dnsmasq.d/capture
+    state: absent
+  when: not captiveportal_enabled
+
 #- name: Restart dnsmasq
 #  systemd:
 #    name: dnsmasq
@@ -102,14 +112,17 @@
 
 # ABOVE DOES NOT WORK ON UBUNTU 16.04 -- what follows is a crude hack (seems to work!)
 
-- name: Stop dnsmasq
+- name: Stop 'dnsmasq' systemd service
   systemd:
     name: dnsmasq
     state: stopped
   when: dnsmasq_enabled | bool
 
-- name: Start dnsmasq
+- name: Start 'dnsmasq' systemd service
   systemd:
     name: dnsmasq
     state: started
   when: dnsmasq_enabled | bool
+
+# TO DO: add important captiveportal_* variable values to {{ iiab_ini_file }} =
+# /etc/iiab/iiab.ini at the end of main.yml here, for /usr/bin/iiab-diagnostics

roles/captiveportal/templates/capture-wsgi.py.j2

@@ -46,9 +46,9 @@ if len(sys.argv) > 1:
       loggingLevel = "DEBUG"
       
 # set up some logging -- selectable for diagnostics
-logging.basicConfig(filename='/var/log/apache2/portal.log',format='%(asctime)s.%(msecs)03d:%(name)s:%(message)s', datefmt='%M:%S',level=loggingLevel)
-logger = logging.getLogger('/var/log/apache2/portal.log')
-handler = RotatingFileHandler("/var/log/apache2/portal.log", maxBytes=100000, backupCount=2)
+logging.basicConfig(filename='{{ nginx_log_dir }}/portal.log',format='%(asctime)s.%(msecs)03d:%(name)s:%(message)s', datefmt='%M:%S',level=loggingLevel)
+logger = logging.getLogger('{{ nginx_log_dir }}/portal.log')
+handler = RotatingFileHandler("{{ nginx_log_dir }}/portal.log", maxBytes=100000, backupCount=2)
 logger.addHandler(handler)
 
 PORT={{ captiveportal_port }}

roles/captiveportal/templates/iiab-divert-to-nginx

@@ -1,4 +1,4 @@
 #!/bin/bash -x
 awk '{print("address=/" $1 "/172.18.96.1")}' /opt/iiab/captiveportal/checkurls > /etc/dnsmasq.d/capture
-echo "#following tells windows 7 that captive portal is active" >>/etc/dnsmasq.d/capture
+echo "#following tells windows 7 that captive portal is active" >> /etc/dnsmasq.d/capture
 echo "address=/dns.msftncsi.com/131.107.255.255" >> /etc/dnsmasq.d/capture

roles/mediawiki/tasks/install.yml

@@ -4,8 +4,6 @@
       - "php{{ php_version }}-intl"
       - "php{{ php_version }}-mbstring"
     state: present
-  #tags:
-  #  - download
 
 - name: Download {{ mediawiki_download_base_url }}/{{ mediawiki_src }} to {{ downloads_dir }}
   get_url:
@@ -22,17 +20,17 @@
     dest: "{{ mediawiki_install_path }}"
     owner: root
     group: "{{ apache_user }}"
-    mode: 0755
+    mode: u+rw,g+r,o+r    # '0755' forced executable bits on files
     keep_newer: yes
 
-- name: Create symlink mwlink from docroot to {{ mediawiki_abs_path }}
+- name: Create symlink {{ doc_root }}/mwlink -> {{ mediawiki_abs_path }}
   file:
     src: "{{ mediawiki_abs_path }}"
-    dest: "{{ doc_root }}/mwlink"
+    path: "{{ doc_root }}/mwlink"
     state: link
 
-- name: Start MySQL service, so we can create db
-  service:
+- name: Start MySQL systemd service ({{ mysql_service }}) so we can create db
+  systemd:
     state: started
     name: "{{ mysql_service }}"
 
@@ -41,7 +39,7 @@
     name: "{{ mediawiki_db_name }}"
     state: present
 
-- name: Create MySQL database user {{ mediawiki_db_user }}
+- name: Create MySQL database user {{ mediawiki_db_user }} with password, and permissions to above db
   mysql_user:
     name: "{{ mediawiki_db_user }}"
     password: "{{ mediawiki_db_user_password }}"
@@ -68,23 +66,21 @@
 
 - name: Configure wgArticlePath variable in {{ mediawiki_abs_path }}/LocalSettings.php
   lineinfile:
-    dest: "{{ mediawiki_abs_path }}/LocalSettings.php"    
+    dest: "{{ mediawiki_abs_path }}/LocalSettings.php"
     line: '$wgArticlePath = "/wiki/$1";'
     create: yes
 
 - name: Configure wgUsePathInfo variable in {{ mediawiki_abs_path }}/LocalSettings.php
   lineinfile:
-    dest: "{{ mediawiki_abs_path }}/LocalSettings.php"    
+    dest: "{{ mediawiki_abs_path }}/LocalSettings.php"
     line: '$wgUsePathInfo = true;'
-    create: yes    
+    create: yes
 
-- name: Install /etc/{{ apache_config_dir }}/mediawiki.conf from template, for http://box{{ mediawiki_url }}
+- name: Install /etc/{{ apache_config_dir }}/mediawiki.conf from template, for http://box{{ mediawiki_url }} via Apache
   template:
     src: mediawiki.conf.j2
     dest: "/etc/{{ apache_config_dir }}/mediawiki.conf"
 
-# Install {{ nginx_config_dir }}/mediawiki-nginx.conf from template in enable.yml
-
 - name: "Add 'mediawiki_installed: True' to {{ iiab_state_file }}"
   lineinfile:
     dest: "{{ iiab_state_file }}"    # /etc/iiab/iiab_state.yml

roles/munin/tasks/enable-or-disable.yml

@@ -27,7 +27,7 @@
   systemd:
     name: "{{ apache_service }}"    # apache2 or httpd, as set in /opt/iiab/iiab/vars/<OS>.yml
     state: restarted
-  when: apache_enabled | bool
+  when: apache_install and apache_enabled
 
 # NGINX
 
@@ -35,7 +35,7 @@
   template:
     src: munin24-nginx.conf.j2
     dest: "{{ nginx_config_dir }}/munin24-nginx.conf"    # /etc/nginx/conf.d
-  when: munin_enabled and nginx_enabled
+  when: munin_enabled    # and nginx_enabled
 
 - name: Disable http://box/munin via NGINX, by installing {{ nginx_config_dir }}/munin24-nginx.conf
   file:
@@ -47,21 +47,4 @@
   systemd:
     name: nginx
     state: restarted
-  when: nginx_enabled | bool
-
-
-- name: Add 'munin' variable values to {{ iiab_ini_file }}
-  ini_file:
-    path: "{{ iiab_ini_file }}"
-    section: munin
-    option: "{{ item.option }}"
-    value: "{{ item.value | string }}"
-  with_items:
-    - option: name
-      value: Munin
-    - option: description
-      value: '"Munin is a networked resource monitoring tool that can help analyze resource trends and ''what just happened to kill our performance?'' problems."'
-    - option: installed
-      value: "{{ munin_install }}"
-    - option: enabled
-      value: "{{ munin_enabled }}"
+  # when: nginx_enabled | bool

roles/munin/tasks/install.yml

@@ -1,4 +1,4 @@
-- name: 'Install 5 packages: munin, munin-node, munin-plugins-extra, libcgi-fast-perl, libapache2-mod-fcgid (debuntu)'
+- name: "Install 5 packages: munin, munin-node, munin-plugins-extra, libcgi-fast-perl, libapache2-mod-fcgid (debuntu)"
   package:
     name:
       - munin

roles/munin/tasks/main.yml

@@ -1,7 +1,22 @@
-- name: Install munin
+- name: Install Munin if it does not appear installed in {{ iiab_state_file }}    # /etc/iiab/iiab_state.yml
   include_tasks: install.yml
-  when: munin_install and not munin_installed is defined
+  when: not munin_installed is defined
 
-- name: Enable munin
-  include_tasks: enable.yml
-  when: munin_install or munin_installed is defined
+- name: Enable or Disable Munin
+  include_tasks: enable-or-disable.yml
+
+- name: Add 'munin' variable values to {{ iiab_ini_file }}
+  ini_file:
+    path: "{{ iiab_ini_file }}"
+    section: munin
+    option: "{{ item.option }}"
+    value: "{{ item.value | string }}"
+  with_items:
+    - option: name
+      value: Munin
+    - option: description
+      value: '"Munin is a networked resource monitoring tool that can help analyze resource trends and ''what just happened to kill our performance?'' problems."'
+    - option: installed
+      value: "{{ munin_install }}"
+    - option: enabled
+      value: "{{ munin_enabled }}"

roles/nginx/tasks/install.yml

@@ -24,9 +24,9 @@
     src: "{{ item.src }}"
     dest: "{{ item.dest }}"
   with_items:
-    - { src: 'roles/nginx/templates/server.conf', dest: '/etc/nginx/' }
-    - { src: 'roles/nginx/templates/nginx.conf', dest: '/etc/nginx/' }
-    - { src: 'roles/nginx/templates/ports.conf', dest: '/etc/{{ apache_service }}/' }
+    - { src: 'roles/nginx/templates/server.conf.j2', dest: '/etc/nginx/server.conf' }
+    - { src: 'roles/nginx/templates/nginx.conf.j2', dest: '/etc/nginx/nginx.conf' }
+    - { src: 'roles/nginx/templates/ports.conf.j2', dest: '/etc/{{ apache_service }}/ports.conf' }
     - { src: 'roles/nginx/templates/uwsgi.service', dest: '/etc/systemd/system/' }
 
 - name: Let uwsgi (running as {{ apache_user }}) write log files

roles/nginx/tasks/main.yml

@@ -16,9 +16,9 @@
     src: "{{ item.src}}"
     dest: "{{ item.dest }}"
   with_items:
-    - { src: 'server.conf', dest: '/etc/nginx/' }
-    - { src: 'nginx.conf', dest: '/etc/nginx/' }
-    - { src: 'ports.conf', dest: "/etc/{{ apache_service }}/" }
+    - { src: 'server.conf.j2', dest: '/etc/nginx/server.conf' }
+    - { src: 'nginx.conf.j2', dest: '/etc/nginx/nginx.conf' }
+    - { src: 'ports.conf.j2', dest: "/etc/{{ apache_service }}/ports.conf" }
     - { src: 'iiab.conf.j2', dest: "{{ nginx_config_dir }}/iiab.conf" }
   when: nginx_enabled | bool
 

roles/nginx/templates/nginx.conf.j2

@@ -42,9 +42,16 @@ http {
 	# Logging Settings
 	##
 
-	access_log {{ apache_log_dir }}/access.log;
-	error_log {{ apache_log_dir }}/error.log;
+   log_format awstats
+   '$remote_addr - $remote_user [$time_local] "$request" '
+   '$status $body_bytes_sent "$http_referer" '
+   '"$http_user_agent" "http_x_forwarded_for"';
+
+	access_log {{ nginx_log_dir }}/access.log awstats;
+	error_log {{ nginx_log_dir }}/error.log;
+
    log_format scripts '$request > $document_root$fastcgi_script_name $fastcgi_path_info';
+   access_log {{ nginx_log_dir }}/scripts.log scripts;
 
 
 	##

roles/nginx/templates/server.conf.j2

@@ -3,10 +3,6 @@ server {
       server_name {{ iiab_hostname }};
       listen 80;
  
-      access_log {{ apache_log_dir }}/access.log;
-      error_log {{ apache_log_dir }}/error.log;
-      access_log {{ apache_log_dir }}/scripts.log scripts;
-
       index  index.php index.html index.htm;
 
       # let individual services drop location blocks in conf.d

roles/sugarizer/tasks/install.yml

@@ -111,7 +111,7 @@
 # gets the job done, for now!)
 
 #- name: Create the express framework for Node.js (OS's other than Fedora 18)
-- name: Run 'npm install --allow-root --unsafe-perm=true' to create /opt/iiab/sugarizer-server/node_modules (CAN TAKE ~5 MINUTES)
+- name: Run 'npm install --allow-root --unsafe-perm=true' to create /opt/iiab/sugarizer-server/node_modules (CAN TAKE ~10 MINUTES)
   command: npm install --allow-root --unsafe-perm=true    # "command:" a bit safer than "shell:"
   args:
     chdir: "{{ iiab_base }}/sugarizer-server"

vars/default_vars.yml

@@ -4,6 +4,10 @@
 
 # Internet-in-a-Box (IIAB) uses True/False to indicate boolean values.
 
+# IIAB does NOT currently support uninstalling apps!  So: if any IIAB app is
+# installed with 'APP_XYZ_install: True' below, do NOT later change that.
+
+
 # IIAB (PRE-)release version number, for {{ iiab_env_file }}
 iiab_base_ver: 7.1
 iiab_revision: 0
@@ -650,8 +654,9 @@ calibreweb_home: "{{ content_base }}/calibre-web"    # /library/calibre-web
 # =============================================================================
 
 
-# PLATFORMS:
-# TURN ALL OFF AND LET /opt/iiab/iiab/vars/<OS>.yml TURN ON AS APPROPRIATE...
+# OS-DEPENDENT VARS: TURN OFF ALL VARS BELOW AND THEN THE CORRECT
+# /opt/iiab/iiab/vars/<OS>.yml WILL TURN ON WHAT'S APPROPRIATE.  See "How This
+# Works" ~30 lines below, and https://github.com/iiab/iiab/wiki/IIAB-Platforms
 
 # Wide to narrow (insofar as poss)
 is_debuntu: False    # Covers all 3: Ubuntu, Debian, Raspbian
@@ -682,7 +687,18 @@ is_fedora_22: False
 is_fedora_18: False
 
 # How This Works:
-# 1. /opt/iiab/iiab/iiab-install copies scripts/local_facts.fact to /etc/ansible/facts.d/local_facts.fact
+#
+# 1. /opt/iiab/iiab/iiab-install copies /opt/iiab/iiab/scripts/local_facts.fact
+#    to /etc/ansible/facts.d/local_facts.fact
 # 2. Ansible runs /etc/ansible/facts.d/local_facts.fact to identify the OS
-# 3. Within /opt/iiab/iiab, ./iiab-install (iiab-stages.yml) or ./runrole (run-one-role.yml) or Admin Console (iiab-from-console.yml) invoke the correct /opt/iiab/iiab/vars/<OS>.yml
-# Longer Explanation: https://github.com/iiab/iiab/wiki/IIAB-Variables (Order of Execution and Precedence)
+# 3. The correct /opt/iiab/iiab/vars/<OS>.yml is then invoked by any the
+#    following high-level scripts in /opt/iiab/iiab for IIAB operators:
+#       ./iiab-install (uses iiab-stages.yml
+#       ./iiab-network (uses iiab-network.yml)
+#       ./runrole (uses run-one-role.yml)
+# 4. Likewise behind the scenes:
+#       ./iiab-configure (uses iiab-from-cmdline.yml)
+#       Admin Console (uses iiab-from-console.yml)
+#
+# More details, including Order of Execution and Precedence:
+# https://github.com/iiab/iiab/wiki/IIAB-Variables

vars/local_vars_big.yml

@@ -4,6 +4,9 @@
 # PLZ READ http://wiki.laptop.org/go/IIAB/local_vars.yml AND http://FAQ.IIAB.IO
 # Orig Idea: branch github.com/xsce/xsce-local for your deployment/community
 
+# IIAB does NOT currently support uninstalling apps!  So: if any IIAB app is
+# installed with 'APP_XYZ_install: True' below, do NOT later change that.
+
 
 # Ansible's default timeout for "get_url:" downloads (10 seconds) often fails
 download_timeout: 200

vars/local_vars_medium.yml

@@ -4,6 +4,9 @@
 # PLZ READ http://wiki.laptop.org/go/IIAB/local_vars.yml AND http://FAQ.IIAB.IO
 # Orig Idea: branch github.com/xsce/xsce-local for your deployment/community
 
+# IIAB does NOT currently support uninstalling apps!  So: if any IIAB app is
+# installed with 'APP_XYZ_install: True' below, do NOT later change that.
+
 
 # Ansible's default timeout for "get_url:" downloads (10 seconds) often fails
 download_timeout: 200

vars/local_vars_min.yml

@@ -4,6 +4,9 @@
 # PLZ READ http://wiki.laptop.org/go/IIAB/local_vars.yml AND http://FAQ.IIAB.IO
 # Orig Idea: branch github.com/xsce/xsce-local for your deployment/community
 
+# IIAB does NOT currently support uninstalling apps!  So: if any IIAB app is
+# installed with 'APP_XYZ_install: True' below, do NOT later change that.
+
 
 # Ansible's default timeout for "get_url:" downloads (10 seconds) often fails
 download_timeout: 200