ansible_samba_ad_dc/README.md

# 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** (Debian, Ubuntu, etc.).

---

## ✅ Features

* 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

### Core Samba / Kerberos variables

| 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.

---

## 📁 Included Task Files

| 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 |

---

## 🧩 Compatibility

* **Operating systems**: Debian 10/11/12 + , Ubuntu 20.04/22.04+  
* **Ansible**: 2.9 + (the role uses only core modules)

---

## 🔒 Security Notes

* 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.  

---

## 📄 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` |

---

## 🛠️ Troubleshooting

| 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. |

--- 

## 📥 Install via Ansible Galaxy

```bash
ansible-galaxy init samba_ad_dc
```

After adding this file, run:

```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!