ilker/maas-samba-ad
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Initial commit: MAAS-deployable Samba Active Directory domain controller

Browse Source 
Builds a Debian image that MAAS deploys to bare metal as an Active Directory
domain controller, with first-boot automation that either creates a domain or
joins an existing one without anyone logging in. To a Windows client the result
is an AD domain: same Kerberos, same LDAP, same Group Policy, same domain join.

The request was for "primary and backup domain controllers", which is NT 4
terminology. Active Directory has no such split — every DC holds a writable copy
and any of them can service a logon. What lives on one DC at a time are the five
FSMO roles, one confusingly named "PDC Emulator". The image therefore offers
provision (create the domain) and join (add another equal DC), which is the
distinction that actually exists.

Contents:

  * customize-samba-ad.sh, run inside the packer-maas build VM: installs samba,
    winbind, Kerberos, chrony and rsync, swaps the cloud kernel for the generic
    one, and deletes every trace of a domain so one image can produce many DCs
  * adc-maas-init, a first-boot state machine covering /etc/hosts, node-unique
    identifiers, time, the resolver, provisioning or joining, the service
    switchover and a self-test that proves Kerberos issues a ticket
  * adc-sysvol-sync, a systemd timer implementing the SYSVOL workaround
  * a MAAS curtin preseed, cloud-init examples, and the release pipeline

Two findings shaped the design.

Debian builds Samba against its bundled Heimdal rather than system MIT Kerberos
— samba-ad-dc does not depend on krb5-kdc — so the AD DC role is in Samba's
supported configuration, not the experimental MIT one. The build asserts this
and fails if it ever changes.

Samba implements neither DFS-R nor FRS, so SYSVOL — where Group Policy lives —
does not replicate between DCs. Left alone, a policy created on one DC never
reaches the others and clients behave differently depending on which DC answered
them, with nothing reporting an error. adc-sysvol-sync applies the Samba wiki's
rsync workaround: sync idmap.ldb once so SID-to-uid mappings agree, rsync the
tree, then samba-tool ntacl sysvolreset because rsync carries POSIX bits while
the Windows ACLs live in AD. Without an SSH key to the source DC it exits with
an explanation rather than letting Group Policy diverge quietly.

Also carried over from maas-proxmox, where they were verified on real hardware:
the curtin-hooks that skip the kernel install and pin interface names by MAC,
Type=simple on the first-boot unit to avoid the systemd ordering cycle, and
shipping networking.service disabled so MAAS owns the network on first boot.
Specific to this image, the Debian cloud kernel is replaced with the generic one
— a bare-metal node booted with the cloud kernel can come up with no disk.

Nothing here has been built or deployed. The README says so at the top and in a
Verified status section that separates what was checked from what was not.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
ilkermanap
2026-09-05 14:44:37 +02:00
commit cf07702535
25 changed files with 3158 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

397
README.md Normal file
View File

@@ -0,0 +1,397 @@
# maas-samba-ad
Build a Debian image that [MAAS](https://maas.io) 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](https://www.samba.org/) 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](#verified-status).
---
## Table of contents
- [If Active Directory is new to you](#if-active-directory-is-new-to-you)
- [What "highly available" means here](#what-highly-available-means-here)
- [The SYSVOL problem](#the-sysvol-problem)
- [How it works](#how-it-works)
- [Requirements](#requirements)
- [Quick start](#quick-start)
- [Deploying a domain](#deploying-a-domain)
- [Configuration reference](#configuration-reference)
- [Operating the domain](#operating-the-domain)
- [Build configuration](#build-configuration)
- [Traps this image works around](#traps-this-image-works-around)
- [Verified status](#verified-status)
- [Licensing](#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](https://wiki.samba.org/index.php/SysVol_replication_(DFS-R))
workaround is to copy SYSVOL with rsync and then reapply the ACLs from AD. This image
ships that as [`adc-sysvol-sync`](overlay/usr/local/sbin/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
```bash
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](#traps-this-image-works-around).
---
## Deploying a domain
### The first DC
```bash
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/`](maas/examples/).
### Then
Point the subnet's DHCP at **both** DCs for DNS, and check the domain from either:
```bash
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`](overlay/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
```bash
# 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](https://github.com/ilkermanap/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](https://github.com/ilkermanap/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](LICENSE).
The build pipeline derives from [`canonical/packer-maas`](https://github.com/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.