update role READMEs

12 files changed, 27 insertions, 15 deletions

diff --git a/roles/apt/README.md b/roles/apt/README.md
index ba2b863..da7f393 100644
--- a/roles/apt/README.md
+++ b/roles/apt/README.md
@@ -1,4 +1,7 @@
+This role upgrades packages on Debian/Ubuntu and installs any additional
+packages.
+
 * Upgrade all installed packages (apt dist-upgrade).
 * Clean up dependencies that are no longer needed (apt autoremove).
-* Install any additional apt packages required on this host.
-* If required, configure unattended-upgrades to install latest security fixes.
+* Optionally, install any additional apt packages required on this host.
+* Optionally, configure unattended-upgrades to install latest security fixes.
diff --git a/roles/apt_repo/README.md b/roles/apt_repo/README.md
index 1e9451e..ffd64ca 100644
--- a/roles/apt_repo/README.md
+++ b/roles/apt_repo/README.md
@@ -1,2 +1,4 @@
-This role is used to enable a 3rd-party repository on Ubuntu/Debian. It
-downloads a key file from the web and adds an entry in /etc/apt/sources.list.d.
+This role enables a 3rd-party repository on Ubuntu/Debian.
+
+* Download a key file from the web to /etc/apt/keyrings.
+* Add an entry in /etc/apt/sources.list.d.
diff --git a/roles/cloud_init_wait/README.md b/roles/cloud_init_wait/README.md
index ecc034e..c4cbe9b 100644
--- a/roles/cloud_init_wait/README.md
+++ b/roles/cloud_init_wait/README.md
@@ -1,4 +1,4 @@
-This role is used to wait until cloud-init is done initializing an instance.
-This is supposed to be the first role in a playbook; it is advisable to disable
-facts gathering so that the playbook can wait until a connection is
-established.
+This role waits until cloud-init is done initializing an cloud VM.
+
+This is supposed to be the first role in a playbook; facts gathering should be
+disabled so that the role can handle connectivity issues.
diff --git a/roles/debian_cloud_server/README.md b/roles/debian_cloud_server/README.md
new file mode 100644
index 0000000..cfb90e7
--- /dev/null
+++ b/roles/debian_cloud_server/README.md
@@ -0,0 +1,2 @@
+This is a meta-role, it simply pulls in other roles as dependencies. It's used
+for general maintenance of all my Debian-based cloud VMs.
diff --git a/roles/file_wait/README.md b/roles/file_wait/README.md
index 0f4c22b..6409dfa 100644
--- a/roles/file_wait/README.md
+++ b/roles/file_wait/README.md
@@ -1,3 +1,5 @@
+This role waits for a file to be present on a host.
+
 This weird and extremely convoluted way to wait until a file exists
 (disregarding reboots) was borrowed from RedHat themselves:
 
diff --git a/roles/firewall/README.md b/roles/firewall/README.md
index 9c1a572..42c16be 100644
--- a/roles/firewall/README.md
+++ b/roles/firewall/README.md
@@ -1,5 +1,5 @@
-This role configures iptables rules in /etc/iptables/rules.v{4,6} to be used by
-iptables-persistent.
+This role configures iptables rules in /etc/iptables/rules.v{4,6}, to be used
+by iptables-persistent.
 
 I found it easier and more flexible to configure a firewall this way; for
 example, I found that cloud provider's firewalls are often less flexible.
diff --git a/roles/linux_status/README.md b/roles/linux_status/README.md
index 4c7b128..167224b 100644
--- a/roles/linux_status/README.md
+++ b/roles/linux_status/README.md
@@ -1,3 +1,3 @@
-This role installs [linux-status] on a Debian server.
+This role installs [linux-status] on a Debian/Ubuntu host.
 
 [linux-status]: https://github.com/egor-tensin/linux-status
diff --git a/roles/ppa/README.md b/roles/ppa/README.md
index f7ce92c..a90a97e 100644
--- a/roles/ppa/README.md
+++ b/roles/ppa/README.md
@@ -1,3 +1 @@
-This role is used to enable an Ubuntu PPA repository; can be used on Debian as
-well. It downloads the repository key and adds the repository in
-/etc/apt/sources.list.d.
+This role is enables an Ubuntu PPA repository; can be used on Debian as well.
diff --git a/roles/router/defaults/main.yml b/roles/router/defaults/main.yml
new file mode 100644
index 0000000..bd165db
--- /dev/null
+++ b/roles/router/defaults/main.yml
@@ -0,0 +1 @@
+router_sysctl_file: /etc/sysctl.d/99-router.conf
diff --git a/roles/router/tasks/main.yml b/roles/router/tasks/main.yml
index 476afb5..ff77a40 100644
--- a/roles/router/tasks/main.yml
+++ b/roles/router/tasks/main.yml
@@ -4,7 +4,7 @@
     name: '{{ item }}'
     value: 1
     reload: true
-    sysctl_file: /etc/sysctl.d/99-router.conf
+    sysctl_file: '{{ router_sysctl_file }}'
   loop:
     - net.ipv4.ip_forward
     - net.ipv4.conf.all.forwarding
diff --git a/roles/systemd_depend_iface/README.md b/roles/systemd_depend_iface/README.md
new file mode 100644
index 0000000..1c68358
--- /dev/null
+++ b/roles/systemd_depend_iface/README.md
@@ -0,0 +1,2 @@
+This is a utility role; it's used to set up a systemd service dependency on
+a network interface.
diff --git a/roles/systemd_depend_mount/README.md b/roles/systemd_depend_mount/README.md
new file mode 100644
index 0000000..c67ecc1
--- /dev/null
+++ b/roles/systemd_depend_mount/README.md
@@ -0,0 +1,2 @@
+This is a utility role; it's used to set up a systemd service dependency on
+a mounted directory.