Jose
36a4ac99ed
Updated the Ansible role to support Debian-based systems (Debian, Ubuntu, etc.) and added new features such as static /etc/resolv.conf, per-host backup of Samba config files, and Molecule tests for both present and absent states.
145 lines
6.2 KiB
Markdown
145 lines
6.2 KiB
Markdown
# 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! |