Pull agents (Windows and Linux)

A small agent on the server checks in with NeverLapse over HTTPS (every minute by default) and installs anything new. You update agents from the Hosts page, or let them update themselves. Nothing has to connect into the server.

Before you install

1. Add the host first (Hosts > Add) with an agent type: Windows - IIS, Windows - General, Veeam Cloud Connect (agent), Microsoft Exchange (agent), Microsoft Remote Desktop Services (agent), Windows - Apache Tomcat, Linux - Apache, Linux - nginx, Linux - Apache Tomcat, Linux - HAProxy, Linux - General or VMware Cloud Director cell. General types need a target directory before an install command appears.
2. Make sure the server can reach NeverLapse on its address and port (443 by default). The address agents use is set under Settings > Server address; put that name in DNS wherever your agents are.
3. Pull agents must be turned on under Settings > Pull Agents.

Each host's page shows its own install key. It identifies the host and lets the agent sign in, so treat it like a password.

Windows agent

Putting a certificate on an IIS site? The IIS walkthrough goes through it step by step with screenshots.

On the host's page, under Install the agent on this host:

1. Get NeverLapseAgent.exe onto the server. On Server 2019 and newer you can fetch it straight from NeverLapse (the exact line, with your server's address, is on the host's page):

   curl.exe -fkLo NeverLapseAgent.exe https://<your NeverLapse address>/download/NeverLapseAgent.exe

   Or download it from the host's page and copy it over.
2. From an elevated Command Prompt:

   NeverLapseAgent.exe /KEY=<the host's install key>

It installs itself as the NeverLapse Cert Agent Windows service (service name NeverLapseAgent) in C:\Program Files\NeverLapse\Agent, fetches its settings and starts checking in. There's also a one-line PowerShell install under Or install straight from the server on the host's page.

• Updates: from the Hosts page, or automatically if you turn that on (see Agent updates). To reinstall, run the same command again.
• Remove it from Settings > Apps (Programs and Features on older Windows), where it's listed as NeverLapse Cert Agent, or run NeverLapseAgent.exe /UNINSTALL from an elevated prompt (silent, for an RMM or a script). See Removing the Windows agent.
• Different address: add /SERVER=https://<name> if the server knows NeverLapse by another name.
• Exchange: for a Microsoft Exchange (agent, pull) host, install the agent on the Exchange server itself, one host per server. See Exchange.
• Remote Desktop Services: for a Microsoft Remote Desktop Services (agent, pull) host, install the agent on the RD Connection Broker, one host per deployment. See Remote Desktop Services.
• Apache Tomcat: for a Windows - Apache Tomcat (agent, pull) host, install the agent on the Tomcat server. See Apache Tomcat.
• NeverLapseAgent.exe /? lists all options.

Removing the Windows agent

From version 1.3.3 the agent is listed in Settings > Apps (Programs and Features on older Windows) as NeverLapse Cert Agent, publisher Live Information Technology Consulting Group, LLC, with its version. It's there however the agent was installed (/KEY=, the PowerShell one-liner, or an older agent that updated itself).

• Uninstall there asks for administrator rights if needed, then stops and removes the NeverLapseAgent service, deletes C:\Program Files\NeverLapse\Agent and the agent's state in C:\ProgramData\NeverLapse\Agent, removes the Apps entry and shows a message when it's done.
• For an RMM or a script, NeverLapseAgent.exe /UNINSTALL from an elevated prompt does the same silently.
• What stays: certificates the agent already placed. Imports in the Windows certificate store and files in the target directory aren't removed.

Linux agent

The simplest way is the one-line install under Or install straight from the server on the host's page: it checks the server and picks the right agent by itself. Or do it in two steps:

curl -fkLo neverlapse-agent https://<your NeverLapse address>/download/neverlapse-agent
sudo chmod +x ./neverlapse-agent && sudo ./neverlapse-agent install --key <the host's install key>

Add --server https://<name> if the server knows NeverLapse by another name. The agent fetches the host's settings, installs itself and runs a first check-in straight away, so you see at once whether it worked.

Which Linux agent you get

The installer prints which one it chose and why. Several certificates on one host need the native agent, and so do nginx and Apache Tomcat hosts. So do VMware Cloud Director cells: on a cell the installer stops with a message instead of falling back to the script agent.

VMware Cloud Director cells

• Install the native agent on each cell, as root (x86_64, systemd), one host per cell. What the agent does with the certificate is on Hosts.
• The first install swaps the certificate straight away if the cell serves a different one, which restarts that cell. Install one cell at a time.
• After a failed swap the old certificate is put back and the agent waits 6 hours before trying again. sudo neverlapse-agent run --force skips the wait.

Commands on the server (as root)

Files: program /opt/neverlapse/neverlapse-agent, settings /etc/neverlapse/agent.json (root only), log journalctl -u neverlapse-agent and /var/log/neverlapse-agent.log.

Moving to the native agent: on a server that runs the script agent, run the install command again. It moves the server to the native agent if it can.

Check-in interval

Agents check in every minute by default. To change it, set Agent check-in on the host's page (1 to 1440 minutes). The Windows and native Linux agents follow it from their next check-in; there's nothing to reinstall. The Linux script agent always runs every minute.

Agent updates

After you upgrade NeverLapse, the Windows and native Linux agents (1.3.0 and newer) can be updated from your NeverLapse server, without touching the servers they run on. Since version 1.3.7 you choose which agents update and when:

• From the Hosts page (the default): every pull host whose agent is older than your server's gets a checkbox. Select the hosts (the box in the header selects every row the search leaves visible) and click Update selected agents, or use Update agent to <version> in a host's ... menu. Each picked agent updates at its next check-in. Cancel update (or Cancel agent update in the menu) takes the pick back if it hasn't happened yet; the pick clears itself once the agent reports the new version.
• Automatically: tick Update agents automatically under Settings > Pull Agents > Agent updates, and every agent updates at its next check-in after you upgrade NeverLapse (how 1.3.0 to 1.3.6 behaved). It's off by default, also on servers upgraded to 1.3.7. The Hosts page toolbar shows whether it's on.

Either way, each agent downloads the newer agent from your NeverLapse server and checks it matches the fingerprint the server announced (the Windows agent also checks our code signature) before replacing itself. The Windows agent keeps its settings and restarts its service. A failed try is retried every hour; the Windows agent logs it to C:\ProgramData\NeverLapse\Agent\update.log.

• Agents from 1.2.9 or older can't be updated this way. Run the host's install command on those servers once; from 1.3.0 on they can be updated from the Hosts page. The Agent column on the Hosts list shows which servers still need it.
• Linux native agent: after it replaces itself it ends that run; the next check-in runs as the new version.
• Linux script agent: doesn't update itself. Run the install command again to update it (or to move to the native agent where the server supports it).
• After an agent upgrade the agent re-applies its certificates once on its next check-in. The same files are rewritten and the same certificate re-imported or rebound, which is harmless.

Agent status

Every check-in reports the machine name, when it last checked in, what it installed and its last error. It's on the host's page under Agent status, the fastest way to see whether a server is checking in.

Which agent version is where

From version 1.3.2 the Hosts list has an Agent column for pull-agent hosts: the version each agent reported at its last check-in and how long ago that was ("checked in 3 min ago"). A badge tells you if anything needs doing:

To find the servers that still need a hand, look down the Agent column after you upgrade NeverLapse: <version> available can be updated from the Hosts page, older agent and re-run install may need their install command run.

The shared token

Under Settings > Pull Agents there's one token all agents use. Regenerating it locks every installed agent out at once until you run its install command again (the commands on the page update by themselves). Do it only if you think the token leaked.

If an agent doesn't pick up a certificate

• Linux: sudo neverlapse-agent status and sudo neverlapse-agent run show what it's doing; history in journalctl -u neverlapse-agent. On the script agent, /var/log/neverlapse-pull.log.
• Waiting for site placements (Apache, nginx, HAProxy): pick at least one site on the host's page.
• Not authorized: the shared token was regenerated; run the install command again.
• Can't connect: check the server reaches the NeverLapse address and port, and that the name resolves there.
• Windows install fails with a TLS or connection error: make sure curl.exe is present (Get-Command curl.exe; built in since Windows 10 1803 / Server 2019) and try curl.exe -k -v https://<your NeverLapse address>/ to see the real error.