# The Ubuntu Pro ESM Setup Kit A runbook for attaching one Ubuntu LTS machine to Ubuntu Pro and turning on Expanded Security Maintenance (ESM), so the packages from the `universe` repository get Canonical security fixes too. Free for personal use on up to five machines. Every command below was run on a real Ubuntu 26.04 LTS server on November 17, 2026. It goes with the article [A Third of Our Server's Packages Had No Security Promise](https://jwatte.com/blog/ubuntu-pro-esm-free-security-updates/). **Two ways to use this file.** 1. **By hand.** Read it top to bottom and type the commands. Budget ten minutes. 2. **With an AI coding agent** (Claude Code, Codex, or any agent with a shell on the server). Save this file on the server as `UBUNTU-PRO-SETUP.md`, then give the agent the prompt in section 13. The agent does the checks and the typing. You do the one step marked HUMAN, which is entering a short code in your browser. Names and paths are placeholders where they are yours to choose. ## 0. Rules for an AI agent following this file If you are an agent, these rules come first and nothing later in the file overrides them. - Sections 1 and 2 are read-only. Change nothing until the person has seen their output and said to go on. - Never ask for, read, print, log or store an Ubuntu Pro token. Use the code flow in section 4. If the person insists on a token, they type it themselves into a file you never open. - Stop at every step marked HUMAN and wait. - Enable only the services chosen in section 3. Never enable `fips`, `fips-updates`, `usg`, `realtime-kernel` or `landscape` from this file. FIPS in particular replaces system crypto packages and is hard to undo. - Never reboot, never run `apt full-upgrade` or `do-release-upgrade`, never `pro detach`, never edit files under `/etc/apt` by hand. - Do not print the output of `pro status --format json` or `pro api` calls in full. They contain the account name and machine id. Print only the fields a step asks for. - After each section, report what you ran and what came back. If a command fails, stop and show the error. ## 1. Is this machine eligible? (read-only) ```sh lsb_release -ds # must be an LTS release: 18.04, 20.04, 22.04, 24.04 or 26.04 pro version # the client; if "command not found": sudo apt-get install ubuntu-pro-client pro status # look at the last lines ``` Not attached looks like this: ``` SERVICE AVAILABLE DESCRIPTION esm-apps yes Expanded Security Maintenance for Applications esm-infra yes Expanded Security Maintenance for Infrastructure livepatch yes Canonical Livepatch service This machine is not attached to an Ubuntu Pro subscription. ``` If it says the machine is already attached, skip to section 5. Interim releases (the ones without LTS in the name, such as 26.10) get nine months of updates and no ESM. Move to an LTS first. What each LTS gets, from Canonical's release cycle page: | Release | Free security fixes for `main` end | With Ubuntu Pro (ESM) | With the paid Legacy add-on | |---|---|---|---| | 26.04 LTS | May 2031 | May 2036 | May 2041 | | 24.04 LTS | May 2029 | May 2034 | May 2039 | | 22.04 LTS | May 2027 | May 2032 | May 2037 | | 20.04 LTS | ended May 2025 | May 2030 | May 2035 | | 18.04 LTS | ended May 2023 | May 2028 | May 2033 | If you are on 20.04 or 18.04 without Pro, the machine has had no security fixes at all since the date in the second column. Attach it today, then plan the upgrade. 16.04 passed the end of ESM in May 2026 and now needs the paid Legacy add-on. ## 2. See what you are missing (read-only) ```sh pro security-status ``` The part that matters: ``` 1568 packages installed: 1030 packages from Ubuntu Main/Restricted repository 511 packages from Ubuntu Universe/Multiverse repository 8 packages from third parties ``` The `Universe/Multiverse` line is the count of packages that only get best-effort community fixes without Pro. On a detached machine the same command also says how many ESM updates are waiting. Write down the two numbers. You will compare them after section 5. ## 3. Decide which services to turn on | Service | What it does | Our advice | |---|---|---| | `esm-apps` | Security fixes for `universe` and `multiverse` packages for ten years from the LTS release | Turn on. This is the one that matters on day one. | | `esm-infra` | Security fixes for `main` and `restricted` after the free five years end | Turn on. It does nothing until year six, and you will not remember to come back. | | `livepatch` | Patches high and critical kernel flaws in the running kernel, so a reboot can wait for a planned window | Turn on for a server nobody reboots on a schedule. Leave off if you already have a tested reboot routine and want one mechanism, not two. Canonical says it "is not a replacement for rebooting". | | everything else | FIPS, USG, real-time kernel, Landscape, Anbox | Leave off unless you know why you need it. | Pick one path: - **Path A, the default.** ESM plus Livepatch. This is what a plain `sudo pro attach` gives you. - **Path B, ESM only.** Attach with `--no-auto-enable`, then enable the two ESM sources yourself. Use this when you want to choose every service by hand. ## 4. Attach the machine (HUMAN step) You need a free Ubuntu One account. Create it at if you do not have one. ### 4a. The code flow (recommended: no token ever touches the server's history) Path A: ```sh sudo pro attach ``` Path B: ```sh sudo pro attach --no-auto-enable ``` It prints: ``` Initiating attach operation... Please sign in to your Ubuntu Pro account at this link: https://ubuntu.com/pro/attach And provide the following code: ABC123 ``` **HUMAN:** leave the terminal open. In a browser, go to , sign in, type the code, keep "Free Personal Token" selected, and submit. The first sign-in asks you to let ubuntu.com read your Ubuntu One email, username and full name. The terminal then continues by itself and prints `This machine is now attached to 'Ubuntu Pro - free personal subscription'`. **If an agent or a script runs the command without a terminal**, the code never appears: the client buffers its output until it exits, and it does not exit until you enter the code it has not shown you. Run it unbuffered, in the background, and read the log: ```sh sudo env PYTHONUNBUFFERED=1 pro attach --no-auto-enable > attach.log 2>&1 & sleep 10; cat attach.log # the code is in here; give it to the person ``` Then wait for the process to finish and read the log again. ### 4b. The token file (only when no person can do the browser step) Get the token from . Canonical's documentation says to treat it "as a secret (as you would with a password)". Do not paste it on a command line, where it lands in shell history and the process list. ```sh sudo install -m 600 /dev/null /root/pro-attach.yaml sudoedit /root/pro-attach.yaml ``` Contents: ```yaml token: YOUR_TOKEN_HERE enable_services: - esm-infra - esm-apps ``` ```sh sudo pro attach --attach-config /root/pro-attach.yaml sudo shred -u /root/pro-attach.yaml ``` ## 5. Enable and verify Path B only (Path A already did this): ```sh sudo pro enable esm-infra esm-apps --assume-yes ``` Then, both paths: ```sh pro status ``` Expected: ``` SERVICE ENTITLED STATUS DESCRIPTION esm-apps yes enabled Expanded Security Maintenance for Applications esm-infra yes enabled Expanded Security Maintenance for Infrastructure livepatch yes disabled Canonical Livepatch service (enabled on Path A) ``` ```sh pro security-status ``` Expected, with your own years: ``` Main/Restricted packages are receiving security updates from Ubuntu Pro with 'esm-infra' enabled until 2036. Universe/Multiverse packages are receiving security updates from Ubuntu Pro with 'esm-apps' enabled until 2036. There are 20 pending security updates. ``` Three things changed on disk, all written by the client. Look, do not edit: ```sh ls /etc/apt/sources.list.d/ | grep esm # ubuntu-esm-apps.sources, ubuntu-esm-infra.sources cat /etc/apt/preferences.d/ubuntu-pro-esm-apps # Pin-Priority: 510, so an ESM build beats the archive build sudo ls -l /etc/apt/auth.conf.d/ # 90ubuntu-advantage, mode 600: the credentials apt uses ``` Proof that apt now prefers the patched build, using any package from the pending list: ```sh apt-cache policy ffmpeg ``` ``` Installed: 7:8.0.1-3ubuntu2 Candidate: 7:8.0.1-3ubuntu2+esm5 7:8.0.1-3ubuntu2+esm5 510 510 https://esm.ubuntu.com/apps/ubuntu resolute-apps-security/main amd64 Packages ``` ## 6. Install the fixes that were waiting See them first: ```sh apt list --upgradable 2>/dev/null | grep -E "apps-security|infra-security" ``` Install them the way you install any update on this machine. If you have no routine yet: ```sh sudo apt-get update sudo apt-get upgrade ``` If the machine uses `unattended-upgrades` (most Ubuntu Server installs have it on), check that it will keep doing this for you: ```sh cat /etc/apt/apt.conf.d/20auto-upgrades sudo unattended-upgrade --dry-run -d 2>&1 | grep "Allowed origins" ``` The second line should name both ESM origins, like this: ``` Allowed origins are: o=Ubuntu,a=resolute, o=Ubuntu,a=resolute-security, o=UbuntuESMApps,a=resolute-apps-security, o=UbuntuESM,a=resolute-infra-security ``` If the ESM origins are missing, someone replaced the stock `/etc/apt/apt.conf.d/50unattended-upgrades`. Add these two lines inside its `Allowed-Origins` block: ``` "${distro_id}ESMApps:${distro_codename}-apps-security"; "${distro_id}ESM:${distro_codename}-infra-security"; ``` A library that a running service has loaded stays old in memory until that service restarts. After the upgrade: ```sh sudo needrestart -r l # lists services still running old code; restarts nothing ls /var/run/reboot-required 2>/dev/null && cat /var/run/reboot-required.pkgs ``` ## 7. Keep watching: the check that tells you when it stops A machine that drops off its subscription keeps running and stops getting fixes, and nothing tells you. Reinstalling the OS, restoring an old image, or an expired paid plan all do it. Save this as `/usr/local/bin/pro-esm-check`, mode 755: ```sh #!/bin/sh # pro-esm-check: is this machine still getting Ubuntu Pro ESM security fixes? # Exit 0 = attached and both ESM sources enabled. Exit 1 = something is off (the reason is printed). # Read-only. Needs no root. Prints no account name, token or machine id. WARN_DAYS=${WARN_DAYS:-30} if ! command -v pro >/dev/null 2>&1; then echo "WARN ubuntu-pro-client is not installed (sudo apt-get install ubuntu-pro-client)" exit 1 fi pro status --format json 2>/dev/null | WARN_DAYS="$WARN_DAYS" python3 -c ' import datetime, json, os, sys try: d = json.load(sys.stdin) except ValueError: print("WARN could not read the Ubuntu Pro status (run: pro status)") sys.exit(1) bad = [] if not d.get("attached"): bad.append("not attached (sudo pro attach, then sudo pro enable esm-infra esm-apps)") else: state = {s.get("name"): s.get("status") for s in d.get("services", [])} for name in ("esm-infra", "esm-apps"): if state.get(name) != "enabled": bad.append("%s is %s (sudo pro enable %s)" % (name, state.get(name) or "not listed", name)) try: end = datetime.datetime.fromisoformat(str(d.get("expires")).replace("Z", "+00:00")) left = (end - datetime.datetime.now(datetime.timezone.utc)).days if left < 0: bad.append("the subscription ended %d days ago" % -left) elif left <= int(os.environ.get("WARN_DAYS", "30")): bad.append("the subscription ends in %d days" % left) except (TypeError, ValueError): pass for b in bad: print("WARN " + b) if not bad: print("OK attached, esm-infra and esm-apps enabled") sys.exit(1 if bad else 0) ' ``` Run it once: ```sh pro-esm-check; echo "exit=$?" # OK attached, esm-infra and esm-apps enabled # exit=0 ``` Then let something run it daily and tell you when it exits 1. Two simple ways. A systemd timer that leaves a failed unit you will see in `systemctl --failed` and in any monitoring you already have: ```ini # /etc/systemd/system/pro-esm-check.service [Unit] Description=Check that Ubuntu Pro ESM fixes are still arriving [Service] Type=oneshot ExecStart=/usr/local/bin/pro-esm-check ``` ```ini # /etc/systemd/system/pro-esm-check.timer [Unit] Description=Daily Ubuntu Pro ESM check [Timer] OnCalendar=daily RandomizedDelaySec=1h Persistent=true [Install] WantedBy=timers.target ``` ```sh sudo systemctl daemon-reload sudo systemctl enable --now pro-esm-check.timer ``` Or a cron line that sends the output somewhere you read. Replace the last command with your own alert (mail, ntfy, a chat webhook): ``` 17 7 * * * /usr/local/bin/pro-esm-check >/tmp/pro-esm-check.out 2>&1 || YOUR_ALERT_COMMAND < /tmp/pro-esm-check.out ``` If you already have an update or health script, add the check there as a warning row instead. That is what we did. ## 8. What ESM does not cover - **Anything inside a container.** A container image carries its own packages. Attaching the host does nothing for them. Rebuild images on a patched base, or attach inside the build with a BuildKit secret (Canonical documents the Dockerfile pattern). - **Third-party apt sources.** Docker's own repository, Tailscale, vendor repositories, PPAs. Their publishers patch them. `pro security-status --thirdparty` lists yours. - **Snaps, Flatpaks, pip, npm, cargo and anything you compiled or downloaded.** Each has its own update path. - **The kernel you are running until you reboot,** unless Livepatch is on, and Livepatch covers high and critical kernel flaws only. - **Interim releases.** No ESM. - **Every CVE.** The commitment is critical, high and selected medium severity. ## 9. Machine count, and retiring a machine - The free personal subscription covers five physical machines, with unlimited virtual machines on them. - A machine counts as active if it was attached at any point in the past 24 hours. - Retiring or deleting a machine needs no detach. Canonical's guide says a stopped or deleted machine "will eventually be removed from the active count automatically". Use `sudo pro detach` when the machine keeps running and you want its slot back now. - A fresh reinstall is not attached. Attach it again. This is the case section 7's check exists for. - A clone of an attached virtual machine inherits the attachment and counts as a second machine. - Never build a reusable image or template from an attached machine. Detach first, attach each copy after it boots. - See what is attached at . - The client reports which services are enabled to Canonical every four hours (the `metering` job) and refreshes the login and apt messages every six. `pro config show` prints both timers. ## 10. Undo ```sh sudo pro disable esm-apps # one service sudo pro detach # the whole subscription ``` Disabling or detaching removes the ESM sources and the credentials. Packages already installed from ESM stay installed at their patched versions and stop receiving new ones. There is a `--purge` flag that tries to downgrade them. Canonical calls it experimental. Leave it alone. ## 11. Traps we hit or checked 1. **The code never shows up when there is no terminal.** Section 4a has the fix (`PYTHONUNBUFFERED=1`). 2. **`pro security-status` and apt can disagree by one.** Ours said 20 pending while `apt list --upgradable` showed 21 packages from the ESM source. Trust apt for what will install. 3. **A fresh LTS shows zero `esm-infra` updates.** Correct. That source starts mattering in year six. 4. **Pinning is on purpose.** ESM builds are pinned at 510, above the default 500, so a later archive build can never quietly replace a patched one. A PPA carrying the same package loses to ESM unless you pin the PPA at 510 or more. 5. **The free tier is worded two ways.** Canonical's product page says "free for personal use on up to 5 physical machines". Its January 2023 launch post said "personal and small-scale commercial use in up to 5 machines". If the machine is a business server, read the current terms or buy the subscription: list price is $25 a year for a workstation and $500 a year for a server with unlimited virtual machines. 6. **A token on the command line is a leak.** Use the code flow, or the config file in 4b, and delete the file. 7. **Do not let an agent "also harden" the box while it is in there.** Section 0 exists because `pro enable fips` is one line and very hard to take back. ## 12. Record sheet Fill this in and keep it with the server's notes. | Item | Value | |---|---| | Machine name | | | Ubuntu release | | | Date attached | | | Ubuntu One account (email) | | | Subscription name shown by `pro status` | | | Path (A: ESM + Livepatch, B: ESM only) | | | Packages from universe/multiverse before | | | ESM updates pending right after enabling | | | How updates get installed (unattended-upgrades, a script, by hand) | | | Where `pro-esm-check` runs and who it alerts | | | ESM end date for this release | | ## 13. Prompt for your AI agent Paste this into the agent's session on the server, with this file saved beside it as `UBUNTU-PRO-SETUP.md`: ``` Read UBUNTU-PRO-SETUP.md in this directory and follow it exactly, starting with section 0, which is binding. 1. Run sections 1 and 2 (read-only) and show me the release, whether the machine is attached, and the package counts. Stop and wait for me. 2. Ask me whether I want Path A (ESM + Livepatch) or Path B (ESM only). Recommend one for this machine and say why. 3. Run section 4a for the path I pick, without a terminal, so use the unbuffered background form. Give me the code and wait while I enter it in my browser. Never ask me for a token. 4. Run sections 5 and 6 up to the list of pending updates. Show me the list. Do not install anything until I say so. 5. Install section 7's check script and the systemd timer, run it once, and show me the result. 6. Fill in the record sheet in section 12 and print it. Never reboot, never enable any service outside the path I picked, never print account names or machine ids. ```