maas-samba-ad

Build a Debian image that MAAS can deploy to bare metal as an Active Directory domain controller, with first-boot automation that either creates a new domain or joins an existing one — without anyone logging in.

The domain controller is Samba in AD DC mode. To a Windows client it is an Active Directory domain: same Kerberos, same LDAP, same Group Policy, same net use, same domain join.

Not tested yet. The code is written and statically checked; nothing here has been built or deployed. See Verified status.

---

Table of contents

• If Active Directory is new to you
• What "highly available" means here
• The SYSVOL problem
• How it works
• Requirements
• Quick start
• Deploying a domain
• Configuration reference
• Operating the domain
• Build configuration
• Traps this image works around
• Verified status
• Licensing

---

If Active Directory is new to you

Skip this if it isn't.

There is no "primary" and "backup" domain controller. That is Windows NT 4 terminology, retired in 2000. In Active Directory every DC holds a full, writable copy of the directory and they replicate to each other. Any DC can service any logon.

What does live on exactly one DC at a time are the five FSMO roles — small coordination duties such as allocating blocks of security identifiers. One of them is called "PDC Emulator", which is where the old name survives and where most of the confusion comes from. Losing the DC that holds them does not cost you the domain; you seize the roles onto another DC and carry on.

So this image has two modes, and they map to the real distinction:

Mode	What it does
AD_MODE=provision	Creates the domain. The first DC, and initially the FSMO holder
AD_MODE=join	Joins the existing domain as another equal DC

A domain is not one service. These have to work together, and all of them except the clock come from the single samba daemon:

Piece	Why it matters
LDAP	The directory itself: users, groups, computers, policy links
Kerberos	Issues the tickets clients actually authenticate with
DNS	Clients find domain controllers through SRV records. AD without working DNS does not function at all — this is the single most common cause of a broken domain
SMB	Serves SYSVOL and NETLOGON, the shares Group Policy and logon scripts live in
Time	Kerberos refuses tickets when clocks differ by more than five minutes. The symptom is logins failing for no visible reason

The image installs and wires up all of them.

Names you have to choose. Two, and they are awkward to change later:

• Realm — your DNS domain in uppercase, e.g. AD.EXAMPLE.COM. Use a domain you control. Do not use your public web domain, and never a bare .local (it collides with mDNS).
• NetBIOS name — the short legacy form, e.g. EXAMPLE. Uppercase, at most 15 characters, no dots. Conventionally the realm's first label.

Passwords. Active Directory enforces complexity by default: at least seven characters, and three of upper case, lower case, digit, symbol. A weak AD_ADMIN_PASSWORD makes provisioning fail with an error that does not say so.

---

What "highly available" means here

Availability in an AD domain comes from having more than one DC, not from clustering anything. Concretely:

1. At least two DCs. Two survives losing one. Three is better, because with two you have no majority when one is down and some operations get cautious.
2. Each DC runs DNS, serving the same AD-integrated zones. This image does that automatically — every DC answers for the domain.
3. Clients must be told about both. Hand out both DC addresses as DNS servers over DHCP. A client that only knows one DC has no redundancy no matter how many you run. In MAAS that is the subnet's DNS server list.
4. Time comes from the DCs. Set AD_NTP_ALLOW so members can use them.
5. SYSVOL has to be replicated. This is the part that does not happen by itself — see below.

The FSMO roles sit on the first DC. If it dies permanently you seize them; the domain keeps authenticating in the meantime.

---

The SYSVOL problem

Read this before relying on the result.

SYSVOL is the share holding Group Policy objects and logon scripts. Windows replicates it between DCs using DFS-R. Samba implements neither DFS-R nor its predecessor FRS, so a policy created on one DC never reaches the others by itself. Clients then behave differently depending on which DC happened to answer them — and nothing reports an error.

The Samba wiki's workaround is to copy SYSVOL with rsync and then reapply the ACLs from AD. This image ships that as adc-sysvol-sync, run by a systemd timer:

1. Sync idmap.ldb from the source DC once. Without it the same file shows different ownership on different DCs, because the SID-to-uid mapping differs.
2. rsync -aAX --delete the SYSVOL tree.
3. samba-tool ntacl sysvolreset, because rsync carries POSIX bits while the Windows ACLs live in AD and have to be reapplied — skip it and clients get access-denied on Group Policy.

It needs a root SSH key on the joining DC that is authorised on the source DC. If there isn't one, the sync exits with an explanation instead of pretending to work. That is deliberate: silent SYSVOL divergence is worse than a visible failure.

This is a real limitation of Samba, not of this image. If you need genuine multi-master SYSVOL replication, you need Windows DCs.

---

How it works

Debian 13 cloud image (qcow2, official)
   │
   ├─ canonical/packer-maas, "debian" template   (QEMU + KVM)
   │     ├─ cloud-init / netplan / curtin compatibility      [upstream]
   │     └─ customize-samba-ad.sh                            [this repo]
   │           ├─ samba, samba-ad-dc, winbind, krb5, chrony, rsync
   │           ├─ swap the cloud kernel for the generic one
   │           ├─ delete every trace of a domain
   │           ├─ mask smbd/nmbd/winbind, disable networking.service
   │           └─ install the overlay (adc-maas-init, sysvol sync, curtin-hooks)
   │
   └─ samba-ad-dc.tar.gz   ──►   maas boot-resources create

On first boot adc-maas-init runs these stages, each once, recorded in /var/lib/adc-maas/<stage>.done:

Stage	What it does
hosts	Makes the FQDN resolve to the management address. Samba insists on this
identity	Regenerates anything that must not be shared between clones
time	Configures chrony, including the signed-NTP socket Windows clients expect
resolver	Points DNS at the DC being joined, then at itself once it serves DNS
domain	samba-tool domain provision or samba-tool domain join
services	Masks the standalone file-server daemons, starts samba-ad-dc
sysvol	Sets up SYSVOL replication where it is needed
selftest	Proves Kerberos issues a ticket and SMB answers

A stage that fails leaves the service failed and is retried on the next boot, rather than leaving a half-configured domain controller that looks fine.

---

Requirements

Build host: Ubuntu 22.04+ with access to /dev/kvm, 4+ vCPU, 8+ GB RAM, 25+ GB free. If it is a VM, nested virtualization must be on and the CPU type must pass the flags through (on Proxmox: --cpu host).

Deployment: MAAS 3.2+ with the curtin preseed from this repository installed on the region controller.

---

Quick start

sudo ./scripts/install-deps.sh     # packer, qemu, ovmf, nbdkit, fuse2fs
sudo make image                    # -> build/samba-ad-dc.tar.gz
make verify
make preseed
sudo make install-preseed          # onto the MAAS region controller
make upload MAAS_PROFILE=admin

The preseed is not optional. Without it the deployment fails — see Traps.

---

Deploying a domain

The first DC

maas $PROFILE machine deploy $SYSTEM_ID \
    osystem=custom distro_series=samba-ad-dc \
    user_data="$(base64 -w0 maas/examples/01-first-dc.yaml)"

with, in that user-data:

AD_MODE=provision
AD_REALM=AD.EXAMPLE.COM
AD_DOMAIN=EXAMPLE
AD_ADMIN_PASSWORD='...'
AD_DNS_FORWARDER=192.0.2.1
AD_NTP_ALLOW=192.0.2.0/24

Every DC after that

AD_MODE=join
AD_REALM=AD.EXAMPLE.COM
AD_DOMAIN=EXAMPLE
AD_JOIN_PEER=192.0.2.10          # an existing DC
AD_ADMIN_PASSWORD='...'          # a Domain Admin on it
AD_SYSVOL_SYNC=on
AD_SYSVOL_SOURCE=192.0.2.10

Full examples: maas/examples/.

Then

Point the subnet's DHCP at both DCs for DNS, and check the domain from either:

samba-tool domain level show
samba-tool drs showrepl          # replication between DCs
samba-tool fsmo show             # who holds the five roles

Security notes

• AD_ADMIN_PASSWORD is plaintext in MAAS user-data, where anyone with MAAS access can read it. Use a short-lived password and change it after the domain is up. It is scrubbed from conf.d on the node once the domain is running (AD_WIPE_SECRETS=true), but not from MAAS.
• The SYSVOL SSH key, if you supply one through user-data, has the same exposure. Use a key dedicated to that job and authorised for nothing else.

---

Configuration reference

Defaults live in /etc/adc-maas/adc-maas.conf, which documents every option. Per-node settings go in /etc/adc-maas/conf.d/*.conf, written by cloud-init from the user-data MAAS supplies, and override the defaults.

Option	Default	Meaning
AD_MODE	none	none, provision or join
AD_REALM	(empty)	Kerberos realm, uppercase DNS domain
AD_DOMAIN	(empty)	NetBIOS name, uppercase, ≤15 chars
AD_ADMIN_PASSWORD	(empty)	Administrator password / join credentials
AD_ADMIN_PASSWORD_FILE	(empty)	Read it from a file instead
AD_JOIN_USER	Administrator	Account used to join
AD_JOIN_PEER	(empty)	An existing DC to join
AD_DNS_BACKEND	SAMBA_INTERNAL	Or BIND9_DLZ if you need BIND's features
AD_DNS_FORWARDER	(empty)	Where to send queries the DC is not authoritative for
AD_FUNCTION_LEVEL	2008_R2	Domain and forest functional level
AD_SITE	Default-First-Site-Name	AD site to join
AD_USE_RFC2307	true	Store POSIX uid/gid in AD
AD_INTERFACE	(auto)	Interface Samba binds to
AD_NTP_ALLOW	(empty)	Subnet allowed to use this DC as a time source
AD_SYSVOL_SYNC	auto	auto (on for joined DCs), on, off
AD_SYSVOL_SOURCE	(join peer)	DC to pull SYSVOL from
AD_SYSVOL_INTERVAL	5min	How often
AD_WAIT / AD_RETRIES	900 / 5	Waiting for the peer, and join attempts
AD_WIPE_SECRETS	true	Scrub the password from conf.d afterwards
AD_ENABLED	true	Set false to disable all first-boot automation

---

Operating the domain

# Users and groups
samba-tool user create alice
samba-tool group addmembers "Domain Admins" alice

# Health
samba-tool drs showrepl                  # is replication working?
samba-tool dns query localhost <realm> @ ALL -U Administrator

# Which DC holds the FSMO roles
samba-tool fsmo show

# The first DC is gone for good: take the roles onto this one
samba-tool fsmo seize --role=all

# A DC that will never come back has to be removed from the directory,
# or replication keeps trying to reach it
samba-tool domain demote --remove-other-dead-server=<name>

Windows clients join the domain exactly as they would against a Windows DC, provided their DNS points at a DC.

---

Build configuration

Variable	Default	Meaning
DEBIAN_SERIES / DEBIAN_VERSION	trixie / 13	Debian release
AD_EXTRA_PACKAGES	acl attr ldap-utils …	Extra packages baked in
IMAGE_NAME	samba-ad-dc	MAAS name and preseed filename
ARCH / BOOT	amd64 / uefi	Architecture and boot mode
DISK_SIZE	16G	Build VM disk; upstream's 4G is too small
PM_REF	pinned SHA	canonical/packer-maas revision
APT_PROXY	(empty)	Local APT cache — see make deps-cache

make check-upstream compares the samba version in Debian against the image you have, without building anything.

---

Traps this image works around

These are the same class of problem as in the sibling maas-proxmox project, and each fails silently:

1. kernel: null in the preseed. Some curtin versions shipped with MAAS crash on it. The image carries /curtin/curtin-hooks instead, which disables the kernel install and works regardless of curtin version.
2. Interface renaming. MAAS records the interface name it saw in its Ubuntu commissioning environment; Debian's udev may name the same card differently, and cloud-init then fails to rename it and leaves the link down. curtin-hooks pins MAC-to-name mappings so udev gets it right from the start.
3. systemd ordering. Ordering the first-boot unit after cloud-final.service while it is WantedBy=multi-user.target forms a cycle, and systemd resolves it by deleting the unit's start job — it never runs and reports nothing. The unit is Type=simple with no cloud-init ordering; the script waits for cloud-init itself.
4. networking.service. ifupdown starting with the build VM's stale interface definition takes the real interface down before any automation runs. It ships disabled, and MAAS owns the network.

Two more are specific to this image:

5. The cloud kernel. The Debian cloud image ships linux-image-cloud-amd64, built for virtual machines and missing most physical-hardware drivers. A bare-metal DC deployed with it can come up with no disk or no network. The build swaps in the generic kernel.
6. A domain baked into the image. Installing the packages leaves a default smb.conf. If that shipped, every machine from the image would start from the same half-configured directory and samba-tool domain provision would refuse to run. The build deletes all of it.

---

Verified status

Nothing in this repository has been built or deployed. It is written and statically checked, no more than that.

Checked

Shell syntax	make lint passes on every script
Generation	make preseed and make customize produce correct output; the embedded overlay round-trips
Samba capability	Debian trixie ships samba 4.22.10, and samba-ad-dc does not depend on krb5-kdc — so it uses the bundled Heimdal KDC, which is Samba's supported configuration for an AD DC. The build asserts this and fails if it ever changes
SYSVOL behaviour	Confirmed against the Samba wiki: no DFS-R, no FRS, rsync plus ntacl sysvolreset is the documented workaround, and idmap.ldb must be synced first
Pattern	The build pipeline, curtin hooks and first-boot state machine are adapted from maas-proxmox, where they were verified end to end on real infrastructure

Not verified

Everything else. Specifically: the image has never been built; no domain has been provisioned or joined; SYSVOL replication has never run; the self-test has never executed; BIND9_DLZ was not tried; no Windows client has been joined to a domain from this image; arm64 is untouched.

Treat the first deployment as a test, and read journalctl -u adc-maas-init -b on the node.

---

Licensing

AGPL-3.0-or-later, see LICENSE.

The build pipeline derives from canonical/packer-maas (AGPLv3) — the curtin preseed and curtin-hooks in particular — so the copyleft carries over. The upstream template is cloned at build time, not vendored.

Samba itself is GPLv3+ and is installed from Debian, unmodified.