update docs

39 files changed, 77 insertions, 39 deletions

diff --git a/roles/apache/README.md b/roles/apache/README.md
index 29b11f0..77f0ec9 100644
--- a/roles/apache/README.md
+++ b/roles/apache/README.md
@@ -36,7 +36,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: webservers
+- name: configure apache
+  hosts: webservers
   roles:
     - role: apache
       vars:
diff --git a/roles/asterisk/README.md b/roles/asterisk/README.md
index e3a03da..aafd9be 100644
--- a/roles/asterisk/README.md
+++ b/roles/asterisk/README.md
@@ -150,7 +150,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: asterisk_servers
+- name: configure asterisk pbx
+  hosts: asterisk_servers
   roles:
     - role: asterisk
       vars:
diff --git a/roles/evolution/README.md b/roles/evolution/README.md
index 938d30b..1f10072 100644
--- a/roles/evolution/README.md
+++ b/roles/evolution/README.md
@@ -34,7 +34,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: linux_desktops
+- name: configure evolution mail client
+  hosts: linux_desktops
   roles:
     - role: evolution
       vars:
diff --git a/roles/firefox/README.md b/roles/firefox/README.md
index 97c2cc0..85fdb17 100644
--- a/roles/firefox/README.md
+++ b/roles/firefox/README.md
@@ -93,7 +93,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: linux_desktops
+- name: configure firefox
+  hosts: linux_desktops
   roles:
     - role: firefox
       vars:
diff --git a/roles/firewalld/README.md b/roles/firewalld/README.md
index 5350b77..86fe3d4 100644
--- a/roles/firewalld/README.md
+++ b/roles/firewalld/README.md
@@ -16,7 +16,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: all
+- name: enable firewalld
+  hosts: all
   roles:
     - role: firewalld
 ````
diff --git a/roles/freebsd_loader/README.md b/roles/freebsd_loader/README.md
index 5c487fb..7cd82b0 100644
--- a/roles/freebsd_loader/README.md
+++ b/roles/freebsd_loader/README.md
@@ -27,7 +27,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: opnsense_firewalls
+- name: configure freebsd bootloader
+  hosts: opnsense_firewalls
   roles:
     - role: freebsd_loader
       vars:
diff --git a/roles/freeipa_client/README.md b/roles/freeipa_client/README.md
index 0ecbe44..9bdf8e4 100644
--- a/roles/freeipa_client/README.md
+++ b/roles/freeipa_client/README.md
@@ -24,7 +24,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: all
+- name: join host to freeipa domain
+  hosts: all
   roles:
     - role: freeipa_client
       vars:
diff --git a/roles/freeipa_server/README.md b/roles/freeipa_server/README.md
index 99a436c..360e4d2 100644
--- a/roles/freeipa_server/README.md
+++ b/roles/freeipa_server/README.md
@@ -53,7 +53,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: freeipa_master
+- name: configure freeipa master server
+  hosts: freeipa_master
   roles:
     - role: freeipa_server
       vars:
@@ -64,7 +65,8 @@ Example playbook:
         freeipa_admin_password: s3cret
         freeipa_ds_password: rea11y_s3cret
 
-- hosts: freeipa_servers:!freeipa_master
+- name: configure freeipa replicas
+  hosts: freeipa_servers:!freeipa_master
   roles:
     - role: freeipa_server
       vars:
diff --git a/roles/freeradius/README.md b/roles/freeradius/README.md
index 4e26c99..e9f20c5 100644
--- a/roles/freeradius/README.md
+++ b/roles/freeradius/README.md
@@ -39,7 +39,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: radius_servers
+- name: configure freeradius
+  hosts: radius_servers
   roles:
     - role: freeradius
       vars:
diff --git a/roles/gathio/README.md b/roles/gathio/README.md
index 16ac169..41a1f9e 100644
--- a/roles/gathio/README.md
+++ b/roles/gathio/README.md
@@ -36,7 +36,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: gathio_servers
+- name: configure gathio web application
+  hosts: gathio_servers
   roles:
     - role: gathio
       gathio_port: 8080
diff --git a/roles/gitolite/README.md b/roles/gitolite/README.md
index ac7688f..29c36c0 100644
--- a/roles/gitolite/README.md
+++ b/roles/gitolite/README.md
@@ -44,7 +44,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: git_servers
+- name: configure gitolite
+  hosts: git_servers
   roles:
     - role: gitolite
       vars:
diff --git a/roles/grub/README.md b/roles/grub/README.md
index d8a9b36..b119420 100644
--- a/roles/grub/README.md
+++ b/roles/grub/README.md
@@ -23,7 +23,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: proxmox_instances
+- name: configure grub bootloader
+  hosts: proxmox_instances
   roles:
     - role: grub
       vars:
diff --git a/roles/hastebin/README.md b/roles/hastebin/README.md
index 7351679..b99b16e 100644
--- a/roles/hastebin/README.md
+++ b/roles/hastebin/README.md
@@ -36,7 +36,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: hastebin_servers
+- name: configure hastebin web application
+  hosts: hastebin_servers
   roles:
     - role: hastebin
       hastebin_port: 8080
diff --git a/roles/invidious/README.md b/roles/invidious/README.md
index a311c29..527b3f5 100644
--- a/roles/invidious/README.md
+++ b/roles/invidious/README.md
@@ -67,7 +67,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: invidious_servers
+- name: configure invidious youtube proxy
+  hosts: invidious_servers
   roles:
     - role: invidious
       vars:
diff --git a/roles/jellyfin/README.md b/roles/jellyfin/README.md
index ca6d85e..1f47193 100644
--- a/roles/jellyfin/README.md
+++ b/roles/jellyfin/README.md
@@ -45,6 +45,10 @@ Example playbook:
 - hosts: invidious_servers
   roles:
     - role: jellyfin
+      vars:
+        jellyfin_access_group: jellyfin-users
+        jellyfin_media_access_group: media-file-access
+        jellyfin_admin_group: jellyfin-admins
 
     - role: apache_vhost
       vars:
diff --git a/roles/journald/README.md b/roles/journald/README.md
index 58ec604..fcafc34 100644
--- a/roles/journald/README.md
+++ b/roles/journald/README.md
@@ -24,7 +24,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: all
+- name: configure systemd journal
+  hosts: all
   roles:
     - role: journald
       vars:
diff --git a/roles/linux_desktop/README.md b/roles/linux_desktop/README.md
index 555c08a..338a885 100644
--- a/roles/linux_desktop/README.md
+++ b/roles/linux_desktop/README.md
@@ -33,7 +33,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: linux_desktops
+- name: configure gnome desktop
+  hosts: linux_desktops
   roles:
     - role: linux_desktop
       vars:
diff --git a/roles/linux_laptop/README.md b/roles/linux_laptop/README.md
index 598170e..ad6bdbf 100644
--- a/roles/linux_laptop/README.md
+++ b/roles/linux_laptop/README.md
@@ -34,7 +34,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: linux_laptops
+- name: perform laptop setup tasks
+  hosts: linux_laptops
   roles:
     - role: linux_laptop
       vars:
diff --git a/roles/local_homedirs/README.md b/roles/local_homedirs/README.md
index 8a42708..63f5fb7 100644
--- a/roles/local_homedirs/README.md
+++ b/roles/local_homedirs/README.md
@@ -19,7 +19,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: linux_desktops
+- name: set up additional home directories on the local disk
+  hosts: linux_desktops
   roles:
     - role: local_homedirs
 ````
diff --git a/roles/locale/README.md b/roles/locale/README.md
index dd28652..fbd8dbc 100644
--- a/roles/locale/README.md
+++ b/roles/locale/README.md
@@ -23,7 +23,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: all
+- name: set the system locale
+  hosts: all
   roles:
     - role: locale
       vars:
diff --git a/roles/motd/README.md b/roles/motd/README.md
index d80239a..d5ef333 100644
--- a/roles/motd/README.md
+++ b/roles/motd/README.md
@@ -14,7 +14,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: all
+- name: remove motd spam
+  hosts: all
   roles:
     - role: motd
 ````
diff --git a/roles/nagios_client/README.md b/roles/nagios_client/README.md
index fffa1bb..e04cb18 100644
--- a/roles/nagios_client/README.md
+++ b/roles/nagios_client/README.md
@@ -23,7 +23,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: all
+- name: configure host as a nagios client
+  hosts: all
   roles:
     - role: nagios_client
       vars:
diff --git a/roles/nagios_server/README.md b/roles/nagios_server/README.md
index ffdbde6..1ca9f84 100644
--- a/roles/nagios_server/README.md
+++ b/roles/nagios_server/README.md
@@ -189,7 +189,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: nagios_servers
+- name: configure nagios monitoring server
+  hosts: nagios_servers
   roles:
     - role: nagios_server
       vars:
diff --git a/roles/nfs_server/README.md b/roles/nfs_server/README.md
index d997eb2..fb7cb74 100644
--- a/roles/nfs_server/README.md
+++ b/roles/nfs_server/README.md
@@ -131,7 +131,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: nas1
+- name: configure nfs/smb exports
+  hosts: nas1
   roles:
     - role: nfs_server
       vars:
diff --git a/roles/nitter/README.md b/roles/nitter/README.md
index 33468ce..1f6d261 100644
--- a/roles/nitter/README.md
+++ b/roles/nitter/README.md
@@ -43,9 +43,13 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: nitter_servers
+- name: configure nitter web application
+  hosts: nitter_servers
   roles:
     - role: nitter
+      vars:
+        nitter_server_name: nitter.example.com
+        nitter_hmac_key: s3cret
 
     - role: apache_vhost
       apache_server_name: '{{ nitter_server_name }}'
diff --git a/roles/nsd/README.md b/roles/nsd/README.md
index eacbe2e..d986e3d 100644
--- a/roles/nsd/README.md
+++ b/roles/nsd/README.md
@@ -36,7 +36,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: authoritative_nameservers
+- name: configure public nameservers
+  hosts: authoritative_nameservers
   roles:
     - role: nsd
       vars:
diff --git a/roles/packages/README.md b/roles/packages/README.md
index af495cb..374a52f 100644
--- a/roles/packages/README.md
+++ b/roles/packages/README.md
@@ -21,7 +21,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: all
+- name: install standard packages
+  hosts: all
   roles:
     - role: packages
       vars:
diff --git a/roles/photostructure/README.md b/roles/photostructure/README.md
index 9c6447e..5f104a1 100644
--- a/roles/photostructure/README.md
+++ b/roles/photostructure/README.md
@@ -47,7 +47,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: photostructure_servers
+- name: install photostructure web application
+  hosts: photostructure_servers
   roles:
     - role: photostructure
 
diff --git a/roles/polkit/README.md b/roles/polkit/README.md
index 2bb8d69..05015d9 100644
--- a/roles/polkit/README.md
+++ b/roles/polkit/README.md
@@ -27,7 +27,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: all
+- name: configure polkit
+  hosts: all
   roles:
     - role: polkit
       vars:
diff --git a/roles/postfix_client/README.md b/roles/postfix_client/README.md
index 38b72ee..0f0d49a 100644
--- a/roles/postfix_client/README.md
+++ b/roles/postfix_client/README.md
@@ -27,7 +27,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: all
+- name: configure postfix mail client
+  hosts: all
   roles:
     - role: postfix_client
       vars:
diff --git a/roles/postfix_server/README.md b/roles/postfix_server/README.md
index 1a6d7de..015f928 100644
--- a/roles/postfix_server/README.md
+++ b/roles/postfix_server/README.md
@@ -75,7 +75,8 @@ Usage
 Example playbook:
 
 ````yaml
-- hosts: mail_servers
+- name: set up public mail server
+  hosts: mail_servers
   roles:
     - role: postfix_server
       vars:
diff --git a/roles/postgresql_server/README.md b/roles/postgresql_server/README.md
index 493bdb0..8e01775 100644
--- a/roles/postgresql_server/README.md
+++ b/roles/postgresql_server/README.md
@@ -25,7 +25,7 @@ Usage
 Example playbook:
 
 ````yaml
-- name: configure postgresql
+- name: configure postgresql database
   hosts: postgresql_servers
   roles:
     - role: postgresql
diff --git a/roles/prosody/README.md b/roles/prosody/README.md
index 45a1f29..ac2d4ea 100644
--- a/roles/prosody/README.md
+++ b/roles/prosody/README.md
@@ -72,7 +72,7 @@ Usage
 Example playbook:
 
 ````yaml
-- name: configure prosody
+- name: configure prosody xmpp server
   hosts: xmpp_servers
   roles:
     - role: prosody
diff --git a/roles/psitransfer/README.md b/roles/psitransfer/README.md
index 2f27bd2..feb406b 100644
--- a/roles/psitransfer/README.md
+++ b/roles/psitransfer/README.md
@@ -40,7 +40,7 @@ Usage
 Example playbook:
 
 ````yaml
-- name: configure psitransfer
+- name: set up psitransfer web application
   hosts: filedrop_servers
   roles:
     - role: psitransfer
diff --git a/roles/root_authorized_keys/README.md b/roles/root_authorized_keys/README.md
index d92aa62..a03822d 100644
--- a/roles/root_authorized_keys/README.md
+++ b/roles/root_authorized_keys/README.md
@@ -24,7 +24,7 @@ Usage
 Example playbook:
 
 ````yaml
-- name: set root authorized_keys
+- name: set authorized_keys for root user
   hosts: all
   roles:
     - role: root_authorized_keys
diff --git a/roles/root_password/README.md b/roles/root_password/README.md
index cc18e77..d02980e 100644
--- a/roles/root_password/README.md
+++ b/roles/root_password/README.md
@@ -24,7 +24,7 @@ Usage
 Example playbook:
 
 ````yaml
-- name: set root password
+- name: set password for root user
   hosts: all
   roles:
     - role: root_password
diff --git a/roles/snmp/README.md b/roles/snmp/README.md
index 8a13fbd..f5c10b5 100644
--- a/roles/snmp/README.md
+++ b/roles/snmp/README.md
@@ -36,7 +36,7 @@ Usage
 Example playbook:
 
 ````yaml
-- name: configure SNMP
+- name: configure SNMP client
   hosts: all
   roles:
     - role: snmp
diff --git a/roles/teddit/README.md b/roles/teddit/README.md
index a77780c..cb9e9bb 100644
--- a/roles/teddit/README.md
+++ b/roles/teddit/README.md
@@ -50,7 +50,7 @@ Usage
 Example playbook:
 
 ````yaml
-- name: configure teddit
+- name: configure teddit web application
   hosts: privbrowse_servers
   roles:
     - role: teddit
diff --git a/roles/ttrss/README.md b/roles/ttrss/README.md
index 7e6c9da..492b270 100644
--- a/roles/ttrss/README.md
+++ b/roles/ttrss/README.md
@@ -51,7 +51,7 @@ Usage
 Example playbook:
 
 ````yaml
-- name: configure tinytinyrss
+- name: configure tinytinyrss web application
   hosts: ttrss_servers
   roles:
     - role: ttrss