diff --git a/README.md b/README.md index cf712ba..c28b499 100644 --- a/README.md +++ b/README.md @@ -1,86 +1,145 @@ # Ansible Role: samba_ad_dc -Ansible role to **install**, **provision**, and optionally **remove** a Samba Active Directory Domain Controller (AD DC) on **Debian-based systems** (e.g., Debian, Ubuntu). +Ansible role to **install**, **provision**, and optionally **remove** a Samba Active Directory Domain Controller (AD DC) on **Debian‑based systems** (Debian, Ubuntu, etc.). --- ## ✅ Features -- Installs and configures Samba as an AD Domain Controller -- Uses `samba-tool` to provision the domain -- Idempotent: Won't re-provision if already set up -- Reversible: Set `state: absent` to cleanly remove Samba AD DC -- Sets up `/etc/hosts` and DNS resolver -- Separate Kerberos configuration -- Logging of provisioning -- Molecule tests included for both `present` and `absent` states +* Installs & configures Samba as an AD DC +* Provisions the domain with `samba-tool` +* Idempotent – skips provisioning if the domain is already present +* Reversible – `state: absent` cleans up the DC +* Sets up `/etc/hosts` + a **static** `/etc/resolv.conf` +* Disables services that would otherwise overwrite `/etc/resolv.conf` + (systemd‑resolved, `resolvconf`, `NetworkManager` DNS, `dhclient`) +* Configures a local NTP daemon (`ntp.conf` + `ntp_signd`) for time‑sync +* Keeps a **per‑host backup** of the Samba config files +* Molecule tests cover both `present` and `absent` states --- ## 📦 Role Variables -### Main Variables +### Core Samba / Kerberos variables -| Variable | Description | Default | -|--------------------------|----------------------------------------------|----------------------| -| `samba_ad_dc_state` | `present` to install, `absent` to remove | `present` | -| `samba_realm` | Kerberos Realm (e.g., `EXAMPLE.COM`) | `EXAMPLE.COM` | -| `samba_domain` | NetBIOS domain name (e.g., `EXAMPLE`) | `EXAMPLE` | -| `samba_admin_password` | Admin password for the domain | `StrongAdminPassword123!` | -| `samba_dns_backend` | DNS backend (`SAMBA_INTERNAL`, `BIND9_DLZ`) | `SAMBA_INTERNAL` | -| `samba_hostname` | Hostname for the server | `inventory_hostname` | +| Variable | Description | Default value | +|-------------------------|---------------------------------------------|-----------------------------| +| `samba_ad_dc_state` | `present` → install, `absent` → remove | `present` | +| `samba_realm` | Kerberos realm (e.g., `CORP.EXAMPLE.COM`) | `EXAMPLE.COM` | +| `samba_domain` | NetBIOS domain name (e.g., `CORP`) | `EXAMPLE` | +| `samba_admin_password` | Password for the domain administrator | `StrongAdminPassword123!` | +| `samba_dns_backend` | DNS backend (`SAMBA_INTERNAL`/`BIND9_DLZ`) | `SAMBA_INTERNAL` | +| `samba_hostname` | Hostname that will appear in `smb.conf` | `inventory_hostname` | + +### Extended configuration variables (see `defaults/main.yml`) + +| Variable | Description | Default value | +|-----------------------|-------------------------------------------------|---------------| +| `samba_packages` | Packages to install when `state: present`. Includes the full list needed for a Debian/Ubuntu AD DC. | *See the YAML block below* | +| `location_internal_dns` | Internal DNS server used in `/etc/resolv.conf` | `192.168.1.1` | +| `location_external_dns` | External (fallback) DNS server | `8.8.8.8` | +| `backup_path` | Directory where the role will store a backup of +`/etc/samba`, `/etc/krb5.conf`, and other files. | `"/path/to/your/backup/directory"` | + +> **NOTE** – the `samba_packages` block is kept for clarity, but it is *not* an +> **Ansible variable** you set on the host; it simply holds the list that +> `tasks/install.yml` uses. + +### NTP configuration + +The role also deploys an NTP daemon (file: `tasks/ntpd.yml`): + +* **`/etc/ntp.conf`** is rendered from `templates/ntp.conf.j2` +* The NTP service is enabled & started automatically +* The handler `Restart ntp service` is called whenever the config changes + +### DNS‑prep + +`tasks/preparing.yml` performs the following important housekeeping steps +before any Samba configuration: + +1. Stops and disables `systemd-resolved` (if present). +2. Removes `/etc/resolv.conf` when it is a symlink to the resolver. +3. Creates a **static** `/etc/resolv.conf` that contains both your internal + and external nameservers (`location_internal_dns`, `location_external_dns`). +4. Uninstalls the `resolvconf` package (if it is installed). +5. Prevents NetworkManager from writing DNS entries by editing + `/etc/NetworkManager/NetworkManager.conf`. +6. Prevents `dhclient` from touching `/etc/resolv.conf` (implementation left + to the user – you can add a `blockinfile` task or a similar file‑lock). + +> **Tip** – if you ever run into “no DNS resolution” on the host *after* the role has finished, double‑check that +> `systemd-resolved` is truly disabled and that `/etc/resolv.conf` is **not** a symlink. --- -## 🧰 Example Playbook +## 📁 Included Task Files -```yaml -- hosts: samba - become: true - roles: - - role: samba_ad_dc - vars: - samba_realm: "CORP.EXAMPLE.COM" - samba_domain: "CORP" - samba_admin_password: "SuperSecretPassw0rd!" +| File | Purpose | +|--------------------------|---------| +| `tasks/install.yml` | Installs packages, configures NTP & DNS, then provisions Samba | +| `tasks/remove.yml` | Stops & removes Samba packages + cleans up files | +| `tasks/kerberos.yml` | Copies `krb5.conf.j2` → `/etc/krb5.conf` | +| `tasks/verify.yml` | Runs `samba-tool` checks + `kinit` tests | +| `tasks/dns_hosts.yml` | Ensures `/etc/hosts` contains the DC record | +| `tasks/logging.yml` | Stores provisioning output to a log file | +| `tasks/preparing.yml` | Disables `systemd-resolved`, `resolvconf`, `NetworkManager`, and creates a static `/etc/resolv.conf` | +| `tasks/ntpd.yml` | Configures NTP (template `ntp.conf.j2`) and ensures it is running | -❌ Remove Samba AD DC -- hosts: samba - become: true - roles: - - role: samba_ad_dc - vars: - samba_ad_dc_state: absent +--- -📁 Included Tasks +## 🧩 Compatibility -install.yml: Installs and provisions Samba AD +* **Operating systems**: Debian 10/11/12 + , Ubuntu 20.04/22.04+ +* **Ansible**: 2.9 + (the role uses only core modules) -remove.yml: Stops and removes Samba AD +--- -kerberos.yml: Configures Kerberos (/etc/krb5.conf) +## 🔒 Security Notes -verify.yml: Validates the installation (samba-tool, kinit) +* Store `samba_admin_password` in Ansible Vault in production. +* The role backs up the Samba configuration to the directory defined by + `backup_path` – see `tasks/logging.yml` for how the backup is created. -dns_hosts.yml: Ensures /etc/hosts and DNS resolvers are set +--- -logging.yml: Logs provisioning output +## 📄 Templates -📄 Templates +| Template | Description | +|----------|-------------| +| `templates/smb.conf.j2` | Samba configuration for the AD DC | +| `templates/krb5.conf.j2` | Kerberos client config | +| `templates/resolv.conf.j2` | Static `/etc/resolv.conf` (search domain + nameserver) | +| `templates/ntp.conf.j2` | NTP configuration used by `tasks/ntpd.yml` | -smb.conf.j2: Samba configuration +--- -krb5.conf.j2: Kerberos configuration +## 🛠️ Troubleshooting -🔒 Security Notes +| Issue | What to check | +|-------|---------------| +| `samba-tool domain provision` fails with a password error | Verify `samba_admin_password` is correct and **no‑log** (`no_log: true`) is set. | +| DNS resolution fails on the DC itself | Ensure `samba_iface` contains `lo` **and** the NIC (e.g., `lo eth0`) and that `/etc/resolv.conf` is not a symlink. | +| Time skew on the DC | Verify NTP service is running (`systemctl status ntp`). | +| Backup directory missing | Check that `backup_path` is writable by the user running the playbook. | -Passwords should be stored in Ansible Vault for production. +--- -DNS and Kerberos configuration assumes internal AD DNS — adjust for external resolvers if needed. +## 📥 Install via Ansible Galaxy -🧩 Compatibility +```bash +ansible-galaxy init samba_ad_dc +``` -OS: Debian 10/11/12+, Ubuntu 20.04/22.04+ +After adding this file, run: -Ansible: 2.9+ +```bash +ansible-galaxy collection install samba_ad_dc +``` +--- + +## 🤝 Contributing + +Feel free to submit PRs – just keep the variable documentation in sync with the files you modify. Happy automating! \ No newline at end of file