Server detection¶

The Agent can read the web and service configuration of the machine it runs on and pre-fill a new certificate workflow from it: which server, which names, which certificate and key files, and (on Linux) which test and reload commands. It also reports the servers it found to CertIntel (Agent 1.9.0+), so the dashboard can list them and pre-fill a workflow for one. It is a convenience for setting up workflows, not a scan:

• Read-only. Detection changes nothing. Nothing is saved until you save the workflow the normal way, after reviewing every pre-filled value.
• This machine only. It reads this machine's configuration files, registry and bindings. It does not scan the network. On a domain controller it makes one connection, to the machine's own LDAPS port (Agent 1.16.0+); see Domain controllers.
• A short list goes to CertIntel, unless you turn that off on the device: see What the Agent reports to CertIntel.
• Not the service on Linux. The Linux service is sandboxed and never detects; detection runs as root. On Windows the service detects.
• CertIntel can ask, not order (Agent 1.14.0+). Check again in the dashboard asks the Agent for a new run. The request names nothing, and the Agent refuses it while reporting is turned off on the device.

What the Agent reports to CertIntel¶

The Agent reports the servers on its computer that use a certificate:

For each server the report holds:

• the kind of server and where it was found (a configuration file and line, a container and mount, or a Windows binding);
• the names it serves and the port;
• the certificate it uses now: the certificate file, or the Windows store, with its thumbprint or fingerprint and its expiry;
• the template and the settings detection suggests for a workflow.

It never holds a private key, the path of a key, or the content of a file. A report lists at most 64 servers.

When detection runs.

• Windows: the service detects when its configuration changes and every 12 hours.
• Linux: detection runs as root: when the Agent is installed or its package is updated, whenever server detection is opened in sudo certintel tui, and with sudo certintel servers detect. The service forwards the result with its next report, within about 5 minutes. The dashboard shows when detection ran.
• Linux, every 24 hours (Agent 1.14.0+): while reporting is on, the service asks the Agent's root hook runner to detect when the saved list is missing or 24 hours old: a few minutes after the service starts, then every 24 hours. The service still detects nothing itself. A run by hand counts, so the next automatic run follows 24 hours after it. This needs certintel-agent-hooks.socket, which every installation enables; without it the Agent logs the problem once and tries again after six hours.
• When the dashboard asks (Agent 1.14.0+): Check again under Detected on this server asks the Agent to detect now, on Linux and on Windows. See Check again.

sudo certintel servers detect             # detect, print the list, leave it for the Agent
sudo certintel servers detect --summary   # one line instead of the list
sudo certintel servers detect --no-save   # print only; nothing new is reported

Turning it off. Reporting is on by default and is turned off on the device only; the dashboard cannot change it:

• certintel config set report-detected-servers=off (on turns it back on);
• Linux: Report detected servers on the terminal interface's Settings screen;
• Windows: Report the servers detected on this computer to CertIntel under Settings → Deployment window in the desktop app. Turning it back on asks for administrator approval.

While it is off the Agent sends no list, and CertIntel forgets the one it held. Detection itself still works on the device. The scheduled run on Linux stops, and a Check again from the dashboard is refused.

Check again¶

Agent 1.14.0+. Check again under Detected on this server asks the Agent to run detection now, so you do not need a session on the server after adding a site. It needs agents.update in the Agent's organization.

1. The dashboard says Asked at …; the agent answers within about a minute (Agent 1.13.0+ asks CertIntel once a minute what changed; the request travels with the Agent's check of dashboard assignments).
2. The Agent detects, sends the new list and reports the outcome. Reload the page to see it: Checked again at …: 3 servers found.

The Agent decides. It does not check again, and says why, when:

A request the Agent has not answered within an hour shows No answer: the server may be switched off or unable to reach CertIntel. One request per Agent is open at a time. An older Agent shows Requires Agent 1.14.0; on Linux run sudo certintel servers detect on the server instead.

What the dashboard shows¶

The Agent's detail pop-out on the Agents page and its workflows page list the servers under Detected on this server, with their names, port, the certificate in use and its expiry, whether a workflow already covers the names or a workflow made on the Agent itself already renews the certificate, and Create workflow, which opens the workflow form filled in. The workflow form has a Detected on this server chooser when one Agent is ticked, and Get a certificate for a server lists the detected servers of the chosen Agent in a menu and starts from the first one on port 443 that has no workflow yet. See Detected servers.

When several detected Windows services can use one certificate (Agent 1.18.0+), the list says One certificate can be used for several of these servers, and the workflow form offers them under Also use this certificate for. See One certificate for several detected servers.

For an NGINX or Apache httpd server on Linux, the form is also filled with the certificate file the server reads now (Agent 1.14.0+), in the setting Certificate file NGINX reads (or Apache httpd reads). A workflow created that way replaces that file and its key file in place, so the server's configuration stays as it is; clear the setting to leave the server's files alone. The list the Agent reports still names no key file: the Agent reads the key file's path from the server's configuration on the machine. See Replacing the files the server already reads. Get a certificate for a server does not use the setting.

The dashboard only proposes. A reported name or setting is used only if it would be accepted when typed; the Agent checks the proposal again, and its local administrator or auto-apply policy decides.

Linux: the terminal interface¶

Detection runs as root, because the configuration and key files it reads are usually readable only by root. Inside sudo certintel tui:

• D on the Workflows screen, or in the post-renewal script manager (S), detects servers and pre-fills a new certificate;
• ctrl+g on the deployment page of the certificate wizard fills in the deployment of the certificate you are editing.

The Detected servers screen says Read from this host's configuration; nothing is changed. Choose one to pre-fill the deployment. and whether the list goes to CertIntel with the Agent's next report. Each entry shows where it was found, its names, certificate, key and chain files, format, expiry, SHA-256 and the test and reload commands. enter uses an entry, esc closes the screen (Server detection closed; nothing was changed.). After you pick one, the terminal interface says Pre-filled from …; check every value before saving. The save page notes that the server reads … today; point it at the files the agent saves instead - the Agent saves to its own folder, and the server configuration must name that location (see Linux service targets).

Without root the terminal interface answers Read-only session: Detect servers changes the agent. Re-run as root: sudo certintel tui.

A file that is broken, missing or cannot be read appears as a note on the entry (for example The key file … could not be read: permission denied), never as an error that stops detection. A path that uses server variables is noted as chosen at run time. One run reports at most 256 servers (More servers were found than one detection run reports (256); the rest are left out.). When a certificate file is readable, its fingerprint and expiry are shown.

A mail or database server without a certificate, or with TLS turned off, is listed with a note that says so, for example No TLS certificate is set (smtpd_tls_chain_files or smtpd_tls_cert_file): the SMTP server does not offer STARTTLS. or ssl is off: PostgreSQL does not offer TLS. Each suggests its starter hook template (Postfix (starter hook) and the others; see Linux service targets), so the workflow saves the files the starter hook installs for the server. The server's configuration must then name the files the hook installs; the entry shows which files it reads today.

The desktop-app path for server detection is refused on Linux: server detection through the desktop app is available only on Windows; on Linux run it from the terminal interface as root.

Windows: the desktop app¶

Both open Servers on this computer; choose one and Pre-fill from this server, then review every value before continuing. Detection is read-only, so it needs no administrator approval (no UAC prompt). The service runs the same detection by itself for its report to CertIntel.

It reads:

• IIS HTTPS bindings (read without saving anything);
• HTTP.sys SSL bindings, recognised as Routing and Remote Access SSTP, DirectAccess IP-HTTPS or WinRM, and as RD Gateway when the TSGateway service exists and a binding on port 443 is present; from Agent 1.18.0 also as SQL Server Reporting Services, AD FS or Web Application Proxy (see SQL Server, Reporting Services and AD FS);
• the SQL Server instances and their TLS certificate setting in the registry (Agent 1.18.0+);
• the WinRM HTTPS listeners and the Remote Desktop listener settings in the registry;
• the LocalMachine Personal, Web Hosting and Remote Desktop stores, read-only, to describe the bound certificates;
• on a domain controller, the certificate it serves for LDAPS (Agent 1.16.0+); see Domain controllers;
• with Network Policy Server installed, the network policies that use a certificate (Agent 1.18.0+); see Network Policy Server.

Notes explain what the Agent found, for example Remote Desktop uses its self-signed certificate., Routing and Remote Access is disabled on this computer. or Microsoft has deprecated DirectAccess; plan a move to Always On VPN. The matching templates are described in Microsoft services.

Domain controllers¶

Agent 1.16.0+. On a domain controller, detection lists Active Directory LDAPS (domain controller) and suggests the template of the same name (see LDAPS on a domain controller). The entry holds:

• the names: the domain controller's full DNS name first, for example dc01.corp.example.com, then the names of the certificate it serves now;
• the port: 636;
• the certificate it serves now: its thumbprint, fingerprint and expiry, and where AD DS has it: its own service store (NTDS\Personal) or the machine Personal store;
• the suggested settings: the domain controller's name as Verification hostname and 636 as Verification port.

A domain controller that serves no LDAPS is listed too, by its name and without a certificate, so you can set a workflow up for it. The dashboard then shows none (nothing answered on the LDAPS port) under Certificate in use, and the desktop app notes Nothing answered a TLS connection on port 636 of this domain controller.

How the certificate is read. AD DS chooses its certificate itself and no setting names it, so the Agent asks the service: it makes one TLS connection to the machine's own LDAPS port (127.0.0.1:636), reads the certificate presented in the handshake and closes the connection. It sends no request, offers no client certificate, signs in to nothing, and the connection never leaves the machine. It is made only on a domain controller and waits at most 5 seconds. On a domain controller the entry is listed first. A computer that is not a domain controller is not asked, and nothing new is listed for it.

The workflow form is filled with the names as they were detected. A public CA issues only for names under a public domain you control, so it cannot issue for a domain controller in a domain such as corp.local; a CertIntel Private CA can, and the LDAPS clients must then trust that CA.

Network Policy Server¶

Agent 1.18.0+. On a computer with the Network Policy Server role, detection lists Network Policy Server (PEAP / EAP-TLS) once for each network policy whose PEAP or EAP-TLS configuration names a certificate from the machine Personal store. The entry holds the policy's name (shown as nps policy <name>), the certificate with its names, thumbprint and expiry, and suggests the Network Policy Server (PEAP / EAP-TLS) template with the policy filled in.

How it is read. NPS keeps its configuration in %SystemRoot%\System32\ias\ias.xml, which also holds the RADIUS shared secrets. The Agent's service opens that file for reading only (at most 8 MB) and keeps nothing but policy names and the thumbprints found in their EAP settings. The shared secrets and everything else in the file are never stored, logged or reported. A file that is missing or cannot be read gives no entries and no error.

SQL Server, Reporting Services and AD FS¶

Agent 1.18.0+.

• A SQL Server instance without a certificate is listed by the computer's DNS name, so you can set a workflow up for it. SQL Server then uses a self-signed certificate it makes when it starts; the dashboard shows none set (SQL Server makes a self-signed one when it starts) under Certificate in use. A note says when Force Encryption is off.
• AD FS binds one certificate for several names (the federation service name, certauth. and others): they are one entry that lists all of them.
• What is left for you: the account that reads the private key (the SQL Server or AD FS service account) is not detected; enter it in the workflow. Two SQL Server instances on one server are told apart by their instance: a workflow covers the instance it names.

Related pages¶

• Detected servers in the dashboard
• Linux service targets
• Microsoft services
• Linux Agent
• Workflow studio & usage
• Monitors & internal endpoints