Requirements#
Get these ready before you install.
The VM#
| Operating system | Ubuntu Server 24.04 LTS (Debian 12 also works) |
| Size | 1 vCPU, 1 GB RAM and 10 GB of disk. The Ubuntu Server setup program needs more memory than the finished server: give the VM 4 GB while you install Ubuntu, then set it to 1 GB. |
| Network | A static IP or DHCP reservation, on a network that can reach the backend servers |
| Internet | Outbound HTTPS for packages, Let's Encrypt and Cloudflare |
The installer adds HAProxy, Python, certbot with the Cloudflare plugin, and everything else it needs.
A DNS name for HAPMan#
Pick a name such as hapman.contoso.com and point it at the VM's internal IP, either:
- as an A record in Cloudflare set to DNS only (grey cloud), or
- in your internal DNS.
The name is needed for HAPMan's certificate and the Entra redirect URI, even though only your LAN (or Global Secure Access) can reach it. The zone must be in Cloudflare for the Let's Encrypt certificate, unless you use a self-signed certificate.
A Cloudflare API token#
HAPMan gets its own certificate from Let's Encrypt with a DNS challenge through Cloudflare, so it needs no inbound ports.
- In Cloudflare, go to My Profile > API Tokens > Create Token and use the Edit zone DNS template.
- Set permissions to Zone · DNS · Edit.
- Limit zone resources to Include · Specific zone · contoso.com.
- Create the token and copy it.
The installer stores it in /etc/hapman/cloudflare.ini, readable by root only, for renewals.
Entra ID#
You create HAPMan's app registration with New-HAPManApp.ps1. Sign in as either:
- a Global Administrator, or
- a Cloud Application Administrator who is also a Privileged Role Administrator (to grant admin consent and assign the app role).
The script asks Microsoft Graph for Application.ReadWrite.All, AppRoleAssignment.ReadWrite.All, DelegatedPermissionGrant.ReadWrite.All, User.Read.All and Group.Read.All for that session only. The app it creates only gets the sign-in scopes openid, profile and offline_access.
People who use HAPMan need the HAPMan.Admin app role, given to them directly or through a group. No Entra admin role is needed to use it.
A Windows or Mac machine#
The recommended way to create the Entra app is from your own machine, not the server.
- PowerShell 7 is recommended. On a Mac, install it with
brew install powershell. - Windows PowerShell 5.1 also works.
- The Microsoft Graph PowerShell modules are installed for you (current user) if they're missing.
No Windows or Mac machine? The installer can create the app from the server instead: see option 2.
Network#
| From | To | Port | For |
|---|---|---|---|
| Internet | Router, forwarded to the HAProxy VM | TCP 443 | HTTPS routes |
| Internet | Router, forwarded to the HAProxy VM | TCP 80 | HTTP routes and the HTTPS redirect (optional) |
| Internet | Router, forwarded to the HAProxy VM | Any other | TCP routes (optional) |
| HAProxy VM | Each backend server | The ports in your routes | Traffic and health checks |
| Your LAN | HAProxy VM | TCP 8443 | HAPMan's web page. Never forward this. |
| HAProxy VM | Internet | TCP 443 | Packages, Let's Encrypt, Cloudflare API, Entra sign-in |
HAPMan's own port can be anything from 1024 to 65535 (8443 by default). It can't be 80 or 443, because HAProxy needs those for your routes. Port 22 and HAPMan's port are reserved, so TCP routes can't use them.