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

ansible-galaxy init samba_ad_dc

After adding this file, run:

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!