Skip to content

Track a new endpoint

What you'll have at the end: a new endpoint visible on the Manage page with served proof — observed by a Scout, scored, and ready to adopt.

Prerequisites: a Scout installed and enrolled on (or with network reach to) the host that serves the endpoint. No Scout yet? Do Scout → Install procedure first.

Time: about 5 minutes of work, plus up to one scan cycle (default 6 hours) of waiting — or no wait at all if you trigger a scan.

Throughout, the examples use the Scout web-01 on the host serving shop.example.com, with the default install root /opt/cyphers.

Step 1 — Add the endpoint to the Scout's targets file

On the Scout's host, append one line — host or host:port — to the targets file (# starts a comment line; a bare host means port 443):

$ echo "shop.example.com:443" >> /opt/cyphers/targets.conf

You should now see the entry when you read the file back:

$ cat /opt/cyphers/targets.conf
# Extra scan targets — one host or host:port per line.
shop.example.com:443

That single line does two things at once:

  • it joins the scheduled scan cycle — the file is re-read at the start of every cycle, so no reload and no restart is needed;
  • it authorizes Hub-initiated scans of that target, so a "Scan now" from the dashboard works immediately.

The file must already be wired

Every generated installer passes --target-file /opt/cyphers/targets.conf to the service, so on a standard install the file exists and is live. If your unit was hand-built without it, add the flag to ExecStart= (the path must be absolute) and restart once — from then on it's append-only.

A line is also a serving declaration

Since SERVE-DECL-1 a targets.conf line means this box serves that endpoint — the Manage page anchors its Scout column on it, which is how two boxes holding the same multi-SAN certificate still show which box serves which hostname. Only list endpoints this box actually serves; the Hub's + Add endpoint and Delete maintain the lines for endpoints you provision through the dashboard.

Step 2 — Trigger a scan (or wait for the next cycle)

The next scheduled cycle picks the target up on its own. To see it now instead, either trigger the Scout's cycle from its host:

$ sudo systemctl reload cyphers-scout

(reload re-reads the cert-dirs file and starts a scan cycle immediately — the fresh cycle reads your new target), or use the Scout's Scan now on its dashboard page (Scouts → web-01).

You should now see, within a couple of minutes, in the Scout's journal:

$ journalctl -u cyphers-scout --since "5 minutes ago" | grep shop.example.com
... scan target=shop.example.com:443 ...

Step 3 — Confirm the endpoint on Manage

Open the dashboard: Manage (https://hub.example.internal/manage).

You should now see a row for shop.example.com — as Untracked: the Hub has observed it serving a certificate (served proof), it is scored, and it is not yet under management. That is the expected resting state of this guide; management is a separate, deliberate step.

Step 4 (optional) — Make its certificate directory visible

If you intend to manage this endpoint's renewals — and especially if you plan to adopt its private key or take over an existing certbot/manual layout — the Scout also needs to see the endpoint's on-disk certificate directory. Add it (absolute path, one per line) and reload:

$ echo "/etc/nginx/ssl" >> /opt/cyphers/cert-dirs.conf
$ sudo systemctl reload cyphers-scout

You should now see in the journal:

cert-dir file reloaded — starting a scan cycle

Unlike the targets file, cert-dir changes take effect on systemctl reload (the service re-reads the file and starts a cycle at once). Directories listed here carry the same authority as --cert-dir flags everywhere — discovery, scan-target trust, and the renewal delivery path policy — so this is also the step that later authorizes renewal delivery to write under that directory. A directory you never list is a directory the Scout will refuse to touch.

Both files fail closed at startup

A targets or cert-dirs file that exists but cannot be parsed stops the service from starting (a running service keeps its last-good list and logs the error instead). Every entry in cert-dirs.conf must be an absolute path; a malformed line is named in the error with its line number.

Alternative: a brand-new endpoint that doesn't serve yet

Everything above tracks an endpoint that already serves a certificate. For a hostname that has nothing serving yet, use + Add endpoint on the Manage page instead: it asks for a renewal profile and an active Scout, creates the endpoint, and starts its first issuance through that profile — issuance-first rather than observe-first. The two paths converge: either way you end with a managed, observed endpoint. The hostname is a plain name (app.example.com, or *.example.com on a DNS-01 profile) — no port, no path; the port has its own field. A malformed name is refused before anything is created, and until the endpoint has been seen serving, its row shows no certificate at all rather than borrowing one from the same Scout's disk.

Where to next