Production install

This page is production install for a Lattice DDI cluster (IPAM + DHCP + DNS adapters): the customer tarball and lattice-install.

If you administer Windows / AD and not Linux, start at windows-admin (SSH vs RDP, WinSCP, sudo). Host sizing, netplan, NTP, ports, entitlement: install-prerequisites. That checklist is what you do before the installer. This page is which installer to run, then where to go next.

Lattice Fleet (many clusters, one console) is a different tarball and a different installer (fleet-install). It does not serve DHCP: fleet-deploy.

Just show me the steps — extract, install, upgrade. Four topologies (cluster, HA cluster, Fleet + clusters, HA Fleet + HA clusters): upgrade.

Vendor documentation (Ubuntu installer checkboxes and Docker Engine packages change). Use Canonical / Docker pages for the latest; this page is the Lattice path.

1. What you are installing

One cluster tarball, Community and paid. The signed entitlement is the SKU. Missing file is Community (1000 managed IPs).

Shared Postgres is HA for dhcpd. There is no ISC-style pairwise failover and no Microsoft failover partner. Client VLANs can be anywhere; they use relays (relays). Extra site: --mode dhcp-only. Active/passive DC is restore + cutover, not a stretched trio — ha.

Kubernetes examples: k8s (Postgres stays external). Prefer lattice-install on Ubuntu unless you already run k8s as a platform.

2. Production (customer tarball)

1. Build the Ubuntu VM(s). install-prerequisites. Windows translations: windows-admin.
2. Download lattice-*-linux-amd64.tar.gz from Downloads. Copy it to /tmp on the VM (WinSCP or PowerShell scp).
3. SSH in and run that archive’s installer:

sudo tar -C /opt -xzf /tmp/lattice-*-linux-amd64.tar.gz
cd /opt/lattice-*-linux-amd64
sudo ./scripts/lattice-install

No arguments opens the wizard (license, host specs, topology, IPs/DNS names, firewall, summary). b goes back a screen. If the host is already installed, the first screen offers Upgrade this node.

Non-interactive:

sudo ./scripts/lattice-install --mode community
# paid HA — full flags: ha.md
sudo ./scripts/lattice-install --mode ha-primary --vip 10.0.0.10 --peers 10.0.0.11,10.0.0.12,10.0.0.13

The installer installs Docker if needed, prints a lattice_live_… token, and writes /etc/lattice/bootstrap.token.

4. Browser on your Windows PC: first-login → first-subnet → relays. Prove a lease (lattice-dhcptest or a real relay). Then names: integrations.

Ubuntu Server 22.04/24.04 (derivatives best-effort). Community UI is HTTPS :443 (self-signed until you replace the cert). HTTP :8080 is loopback-only.

Upgrade / patch

Same command for a bugfix or a new minor. Download the new tarball. Run that archive’s installer, not lattice-install already on PATH. From a Windows PC: copy the .tar.gz onto the Linux VM with WinSCP or PowerShell scp, then SSH in:

sudo tar -C /tmp -xzf /tmp/lattice-*-linux-amd64.tar.gz
sudo /tmp/lattice-*-linux-amd64/scripts/lattice-install --mode upgrade

• Single node: this VM restarts (~1–2 minutes). Console and DHCP on this box blip; leases stay in Postgres; clients retry.
• Three-node HA: replica, replica, then leader. Other nodes keep serving. --force if Patroni switchover stalls. ha.
• Extra dhcp-only / dns-only: same command on that leaf.

Do not downgrade. Console Help → Upgrade this node. Air-gap: lattice-install --mode save-bundle on a connected host, copy the image tar with the release, --bundle on the dark site. Fleet-first rolling order and the two-cut window: upgrade.

3. If you are not using lattice-install

Most sites should stop at §2. This section is BYO Postgres, systemd units from the tarball (deploy/systemd/), or a UDP VIP you assemble yourself. Clock sync still applies: chrony or timedatectl NTP synchronized, UTC, alert if offset > 500 ms (GSS-TSIG fails opaquely beyond ~5 minutes vs DCs).

Manual shape: 3-node Patroni or managed Postgres with failover. Single writer. 2+ dhcpd. Relays point at one address. Health-check HTTP /readyz, not UDP/67. Binaries: lattice-api, lattice-dhcpd, lattice-worker, lattice-dns, lattice-maint, lattice. Paid BYO: lattice-install --mode byo-postgres --pg-dsn '…' still exists if you want the installer to place units against your DSN.

systemd

Units in deploy/systemd/. Install binaries to /usr/local/bin, env to /etc/lattice/lattice.env (mode 0600):

LATTICE_PG_DSN=postgres://lattice_dhcpd@pg-primary:5432/lattice?sslmode=require
LATTICE_NODE_NAME=dhcp-a
LATTICE_LISTEN_DHCP=:67
LATTICE_LISTEN_HTTP=:8080
LATTICE_LOG_LEVEL=info
LATTICE_QUARANTINE_TTL=15m
LATTICE_ENTITLEMENT_PATH=/etc/lattice/entitlement.json

Place the signed entitlement at /etc/lattice/entitlement.json (mode 0640). Missing file is community (1000 managed IPs). See license.

lattice-dhcpd.service uses CAP_NET_BIND_SERVICE for :67 without a full root unit. Give each dhcpd host a unique LATTICE_NODE_NAME. Do not run dhcpd and api on the same LATTICE_LISTEN_HTTP port on one host.

Roles, backup, PgBouncer: postgres. Adding a third dhcpd: runbooks.

UDP VIP

Relays point at one address. Health-check HTTP /readyz, not UDP/67:

• keepalived + IPVS — paid HA (deploy/ha/keepalived.conf). Open-source HAProxy has no generic mode udp. LVS rr on UDP/67 and UDP/53. Still gate real servers on HTTP /readyz (DHCP) and /healthz (DNS).
• HAProxy Enterprise UDP — optional snippet: deploy/haproxy/dhcp.cfg. Not used by lattice-install.

Anycast is acceptable the same way: withdraw the route when /readyz fails.

Process config

Network intent lives in Postgres. Process config is env (+ optional YAML LATTICE_CONFIG).

Prometheus text on /metrics (api, dhcpd, worker): lattice_up, lattice_dhcp_allocations_total / lattice_dhcp_naks_total, lattice_dhcp_offer_latency_seconds, lattice_db_query_total, lattice_pool_free, lattice_outbox_lag, lattice_dns_updates_total{result}. DHCP logs are JSON slog with node, xid, mac, ip, subnet_id, msg_type. Scrapes and SIEM: observability.

Related

• install-prerequisites — VM before lattice-install
• ha — paid three-node cluster HA
• fleet-deploy — Fleet control plane (different tarball)
• windows-admin — SSH, WinSCP, sudo

Just the steps

Cluster (this tarball), from a Windows PC: copy lattice-*-linux-amd64.tar.gz to /tmp on the Ubuntu VM (WinSCP). SSH:

sudo tar -C /opt -xzf /tmp/lattice-*-linux-amd64.tar.gz
cd /opt/lattice-*-linux-amd64
sudo ./scripts/lattice-install
sudo cat /etc/lattice/bootstrap.token
curl -sf http://127.0.0.1:8080/readyz && echo OK

Browser: https://<vm-or-vip> — first-login. Prefix → subnet → pool: first-subnet. Relays: relays. Paid HA installer flags: ha.

Upgrade:

sudo tar -C /tmp -xzf /tmp/lattice-*-linux-amd64.tar.gz
sudo /tmp/lattice-*-linux-amd64/scripts/lattice-install --mode upgrade

Four scenarios (including Fleet first, then rolling cluster): upgrade. Fleet (different archive): fleet-deploy.