Optimized READMEs

roles/sshd/README.md

@@ -1,26 +1,35 @@
-# SSHD
+# sshd
 
 ## Description
 
-This role configures the SSH daemon ([sshd](https://man7.org/linux/man-pages/man5/sshd_config.5.html)) on the target system by deploying a templated configuration file. It ensures that secure and proper SSH settings are applied, reducing the risk of misconfiguration and potential lockout.
+This Ansible role configures the OpenSSH daemon (`sshd`) by deploying a templated `sshd_config` file. It applies secure, best-practice settings—such as disabling root login, enforcing public-key authentication, and setting appropriate logging levels—to harden remote access and reduce the risk of misconfiguration or lockout.
 
 ## Overview
 
-Optimized for secure remote access, this role:
-- Generates an SSH daemon configuration file from a Jinja2 template.
-- Sets appropriate ownership and permissions on the configuration file.
-- Notifies systemd to restart the SSH daemon when changes are made.
-
-## Purpose
-
-The primary purpose of this role is to establish a secure SSH environment by deploying a well-configured sshd_config file. This helps prevent unauthorized access and potential system lockouts, while ensuring that the SSH service runs smoothly.
+- Renders `sshd_config.j2` into `/etc/ssh/sshd_config` with customizable options  
+- Sets file ownership (`root:root`) and permissions (`0644`)  
+- Automatically reloads and restarts the SSH service via a Systemd handler  
+- Uses a `run_once_sshd` fact to ensure idempotent execution  
 
 ## Features
 
-- **SSH Configuration Deployment:** Creates an sshd_config file with best-practice settings.
-- **Systemd Integration:** Automatically restarts the SSH service upon configuration changes.
-- **Security Enhancements:** Enforces secure defaults such as disabled root login and public key authentication.
+- **Templated Configuration**  
+  Delivers a Jinja2-based `sshd_config` with variables for debug logging and PAM support.
 
-## Other Resources
-- https://www.google.com/search?client=firefox-b-d&q=sshd+why+to+deactivate+pam
-- https://man7.org/linux/man-pages/man5/sshd_config.5.html
+- **Security Defaults**  
+  - Disables password (`PasswordAuthentication no`) and root login (`PermitRootLogin no`)  
+  - Enforces public-key authentication (`PubkeyAuthentication yes`)  
+  - Conditionally sets `LogLevel` to `DEBUG3` when `enable_debug` is true  
+
+- **Systemd Integration**  
+  Handles daemon reload and service restart seamlessly on configuration changes.
+
+- **Idempotency**  
+  Ensures tasks run only once per play by setting the `run_once_sshd` fact.
+
+## Further Resources
+
+- [sshd_config Manual (OpenSSH)](https://man7.org/linux/man-pages/man5/sshd_config.5.html)  
+- [Ansible Template Module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/template_module.html)  
+- [Ansible Shell & Handler Best Practices](https://docs.ansible.com/ansible/latest/user_guide/playbooks_handlers.html)  
+- [OpenSSH Security Recommendations](https://www.openssh.com/security.html)