GSS-TSIG to Active Directory

Lattice updates AD-integrated DNS zones after DHCP, the same job Microsoft DHCP did with “Name Protection” / DHCP credentials. It does not join the domain, talk LDAP, host the forest, or log anyone into the Lattice console.

Adapter: ad_gsstsig. Allowed on every entitlement tier, including community.

The worker runs nsupdate -g (BIND tools + Kerberos). That is the default (LATTICE_GSS_TSIG_MODE=subprocess). nsupdate must be on PATH on every host that runs the worker (Ubuntu: dnsutils).

Hub: integrations. Stubs vs resolvers: dns-how. BIND (no Kerberos): bind-ddns.

Vendor documentation (use these for UI labels, flags, and anything that changed after we wrote this page):

Our walkthrough is the Lattice-specific path (principal, keytab path, worker env). Microsoft, ISC, and Samba remain the source of truth for their tools.

Just show me the steps — commands and click path at the bottom, without the education.

1. What problem this solves

A Windows network usually looks like this:

  laptop  --DHCP Discover-->  relay  -->  Lattice dhcpd
  laptop  --option 6------->  Domain controllers (AD DNS + often recursion)

After Ack the laptop has an IP. It still has no name in DNS unless something writes host.ad.example.com A (and the PTR) into the zone the DCs host.

Microsoft DHCP did that as the DHCP server, using a domain account. Lattice does it as the worker, a few hundred milliseconds later, using Kerberos (GSS-TSIG) so the DC will accept an RFC 2136 update on a zone set to secure only.

Ack never waits. If the DC is down, the lease is still valid; Work → DNS shows the failed update.

What this is not

2. Why a keytab (and what Kerberos is doing)

GSS-TSIG means: “prove you are this AD user, then I’ll apply your UPDATE.”

A keytab is a small binary file that holds a Kerberos principal and its long-term key (derived from the account password). The Lattice worker uses it instead of typing a password:

1. Worker sets KRB5_CLIENT_KTNAME to the keytab path and KRB5_PRINCIPAL to the principal you configured.
2. nsupdate -g obtains tickets from a KDC (a DC).
3. It opens a TKEY/GSS session to the DNS server you put in host.
4. It sends update add / update delete for A and PTR.

If clocks differ by more than about five minutes, Kerberos fails. The error is often NOTAUTH or a terse nsupdate message. NTP on Lattice and the DCs is a hard dependency (it already is for DHCP leases).

The principal is an identity, not a secret. The keytab file is the secret. Mode 0600, lattice user, never in git, never in the IPAM UI (store file:/etc/lattice/lattice.keytab).

3. What to create in Active Directory

Use a dedicated user. Do not reuse a Domain Admin, a helpdesk mailbox, or the computer account of a DC.

3.1 Account

In Active Directory Users and Computers (or equivalent):

1. Create svc-lattice-dns in an OU you control (not Users if you can avoid it).
2. Password: long and random. You will paste the same string into ktpass (that command resets the account password by default; see Microsoft’s /pass and /setpass notes).
3. Clear User must change password at next logon.
4. Prefer Password never expires or a documented rotation (see §8). An expired password with a stale keytab is a typical overnight outage.
5. On the Account tab, select This account supports Kerberos AES 256 bit encryption. Clear DES/RC4 if your domain policy allows it.

Do not grant interactive logon. Do not add the account to Domain Admins or Enterprise Admins. Prefer zone ACLs over DnsAdmins. Do not put this account in DnsUpdateProxy unless you have followed Microsoft’s extra steps for that group — records created by that group are not secured the way a dedicated credential is.

3.2 Permissions on the zones Lattice will update

Lattice only needs to create/delete the names it writes (lease hostnames and PTRs), not administer DNS.

On each forward and reverse zone you will point a Lattice subnet at:

1. DNS Manager → zone → Properties → Security.
2. Add svc-lattice-dns.
3. Allow Create all child objects, Delete all child objects, and Write. For a tighter ACL, grant those on a dedicated DNS node (harder to operate; start with zone-level).

The zones must already exist and be AD-integrated. Dynamic updates: Secure only is the usual setting; that is why we use GSS-TSIG instead of a BIND TSIG key.

Reverse zones (20.20.10.in-addr.arpa. for 10.20.20.0/24) are easy to forget. Without them, A succeeds and PTR sits in Work → DNS as PTR …. Lattice will not create the zone for you.

Do not grant this account rights on _msdcs, forest-wide partitions, or zones Lattice must not touch.

4. Create the keytab

ktpass maps an AD user to a Kerberos principal and writes a MIT-format keytab. Run it on a domain-joined Windows machine with RSAT, as a Domain Admin or as a delegated admin who can reset that user’s password. Microsoft always wants /crypto specified (the default follows older MIT behavior).

Replace EXAMPLE.COM / EXAMPLE with your realm (usually the DNS forest name, uppercase) and NetBIOS domain. Slash (/) or dash (-) flags both work:

ktpass /princ [email protected] /mapuser EXAMPLE\svc-lattice-dns ^
  /crypto AES256-SHA1 /ptype KRB5_NT_PRINCIPAL ^
  /pass "the-password-you-set" /out C:\temp\lattice.keytab

What those flags mean:

Copy lattice.keytab to each Lattice worker host (HA: every control node). From Windows, copy the file with WinSCP to /tmp on the VM, then SSH:

sudo mv /tmp/lattice.keytab /etc/lattice/lattice.keytab
sudo chown lattice:lattice /etc/lattice/lattice.keytab
sudo chmod 600 /etc/lattice/lattice.keytab

From Linux/macOS:

scp lattice.keytab YOURUSER@lattice-1:/tmp/lattice.keytab
ssh YOURUSER@lattice-1 'sudo mv /tmp/lattice.keytab /etc/lattice/lattice.keytab && sudo chown lattice:lattice /etc/lattice/lattice.keytab && sudo chmod 600 /etc/lattice/lattice.keytab'

chmod 600 means only that account can read the file (NTFS “SYSTEM only”). windows-admin §7.

Linux-side alternatives

If you already administer AD from Linux (Samba DC, or samba-tool against a DC):

samba-tool domain exportkeytab /etc/lattice/lattice.keytab \
  [email protected]
chmod 600 /etc/lattice/lattice.keytab

msktutil is aimed at computer accounts; prefer a user + ktpass unless you already have a machine-account story.

Older docs / service-style principals

Some setups use /princ DNS/[email protected] mapped to the same user. That can work if the keytab and Lattice GSS principal field are identical. Prefer [email protected] unless you already standardized on a DNS/ SPN.

5. Kerberos on the Lattice worker (krb5.conf)

The worker is a Kerberos client. It must know the realm and how to find a KDC. On many domain-joined Linux hosts dns_lookup_kdc = true is enough. On a typical Lattice VM (not domain-joined) install krb5-user (Debian/Ubuntu) or krb5-libs (RHEL) and set /etc/krb5.conf:

[libdefaults]
    default_realm = EXAMPLE.COM
    dns_lookup_kdc = true
    rdns = false
    ticket_lifetime = 24h
    default_tkt_enctypes = aes256-cts-hmac-sha1-96
    default_tgs_enctypes = aes256-cts-hmac-sha1-96

[realms]
    EXAMPLE.COM = {
        kdc = dc01.example.com
        kdc = dc02.example.com
        admin_server = dc01.example.com
    }

[domain_realm]
    .example.com = EXAMPLE.COM
    example.com = EXAMPLE.COM

rdns = false avoids PTR-required SPN mismatches on networks without reverse DNS for the Lattice box.

6. Prove the keytab before you involve Lattice

On the worker, as a user that can read the keytab:

klist -k -t /etc/lattice/lattice.keytab
# should list [email protected] (and kvno)

kinit -k -t /etc/lattice/lattice.keytab [email protected]
klist
kdestroy

nsupdate must be on PATH (apt install bind9-utils or dnf install bind-utils).

export KRB5_CLIENT_KTNAME=/etc/lattice/lattice.keytab
export [email protected]
nsupdate -g <<'EOF'
server dc01.example.com
update add lattice-probe.example.com. 300 A 10.20.20.250
send
EOF

Then delete it:

nsupdate -g <<'EOF'
server dc01.example.com
update delete lattice-probe.example.com. A
send
EOF

If this fails, Lattice will fail the same way. Fix Kerberos/ACL/clock here first.

7. Point Lattice at AD

Worker environment (optional — this is already the default):

LATTICE_GSS_TSIG_MODE=subprocess

Install BIND’s dnsutils if nsupdate is missing. Console More → DDNS adapters → Add:

API equivalent:

{
  "adapter": "ad_gsstsig",
  "name": "ad",
  "host": "dc01.example.com",
  "gss_principal": "[email protected]",
  "keytab_ref": "file:/etc/lattice/lattice.keytab"
}

On each subnet: enable DDNS, adapter ad, forward zone example.com (or the zone you actually use for DHCP names), reverse zone matching the subnet (10.20.20.0/24 → 20.20.10.in-addr.arpa). Hostnames on leases are a single DNS label; the FQDN is that label plus the forward zone.

Option 6 stays the DCs.

Grant a test lease (or lattice-dhcptest). Work → DNS should go quiet. nslookup <host> dc01.example.com should show the A.

8. Rotation and HA

• Password / keytab rotation: mint a new keytab (ktpass resets the password). Install the file on all workers, then the old file is dead. In-flight outbox rows retry.
• HA: the keytab path must exist on every node that runs lattice-worker. Postgres stores only the ref.
• Do not restore an old keytab after ktpass; kvno will not match the DC.

9. Troubleshooting

Support: never collect the keytab. Principal, keytab path, DC hostname, clock offset, and a redacted nsupdate error are enough.

Just the steps

Replace EXAMPLE.COM / EXAMPLE, the DC name, the password, and the probe name. Confirm ktpass flags on Microsoft Learn.

1. AD Users: create svc-lattice-dns. Long random password. Clear User must change password at next logon. Prefer Password never expires. Account tab: Kerberos AES 256 bit encryption. Not Domain Admin. Not DnsUpdateProxy unless you followed Microsoft’s extra steps.
2. DNS Manager: on each forward and reverse zone Lattice will write, grant that user Create/Delete all child objects and Write. Zones AD-integrated, Secure only. Not _msdcs.
3. On a domain-joined Windows box (RSAT):

ktpass /princ [email protected] /mapuser EXAMPLE\svc-lattice-dns ^
  /crypto AES256-SHA1 /ptype KRB5_NT_PRINCIPAL ^
  /pass "the-password-you-set" /out C:\temp\lattice.keytab

4. Copy the keytab to each worker with WinSCP → /tmp, then SSH:

sudo mv /tmp/lattice.keytab /etc/lattice/lattice.keytab
sudo chown lattice:lattice /etc/lattice/lattice.keytab
sudo chmod 600 /etc/lattice/lattice.keytab
sudo apt-get install -y krb5-user bind9-utils

5. /etc/krb5.conf — realm EXAMPLE.COM, dns_lookup_kdc = true, KDCs = your DCs (full example in §5).

klist -k -t /etc/lattice/lattice.keytab
kinit -k -t /etc/lattice/lattice.keytab [email protected] && kdestroy
export KRB5_CLIENT_KTNAME=/etc/lattice/lattice.keytab
export [email protected]
nsupdate -g <<'EOF'
server dc01.example.com
update add lattice-probe.example.com. 300 A 10.20.20.250
send
update delete lattice-probe.example.com. A
send
EOF

6. Worker: nsupdate on PATH. Default env is LATTICE_GSS_TSIG_MODE=subprocess. Console More → DDNS adapters: adapter ad_gsstsig, host = a DC, GSS principal = [email protected], keytab ref = file:/etc/lattice/lattice.keytab.
7. Subnet: DDNS on, adapter name, forward + reverse zones. Option 6 stays the DCs. Forest is not embedded.