Installing the agent

The Tenvara agent is one small service for Windows, macOS and Linux. It keeps a single encrypted connection to your Tenvara server and runs the modules you switch on: inventory, remote control, monitoring, patching, software, scripts, backup, diagnostics and more. You install it with an enrolment token, which ties the device to a customer (and optionally a site) from the moment it connects.

Supported systems#

The same list is under Supported systems on Devices > Enrolment, the Installers tab, and Supported systems says which part of the agent runs where.

The main agent's installer checks the Windows version before anything is copied. On Windows 7 SP1, 8.1, Server 2008 R2 SP1, 2012 or 2012 R2 it stops and points you to the Lite agent, which has its own packages on the same tab. Anything older is refused with a clear message. The install command reports a refusal back, so the token's Refused column on Devices > Enrolment shows how many machines were turned away and why.

Create an enrolment token#

1. Go to Devices and click Add devices, or open Devices > Enrolment and click New token.
2. Choose the Customer. Devices enrolled with this token belong to that customer.
3. Optionally choose a Site. Devices enrolled with the token are placed there.
4. Give the token a Name so you can tell tokens apart later, for example Office rollout.
5. Set Expires after (1 day, 7 days, 30 days, 90 days, 1 year or never) and, if you want, a Maximum devices limit. Leave the limit empty for no limit.
6. Click Create token.

Tenvara then shows the token and a ready-to-paste install command for each platform.

What happens to new devices#

Click a token on Devices > Enrolment to open it, then click Change under New devices to choose what happens to each device it enrols. Devices already enrolled are not changed.

• Hold new devices for approval: a new device waits on Devices > Enrolment, the Waiting for approval tab, without monitoring or remote access, until someone approves it. You are told when one arrives.
• Device group: new devices are added to it, so the group's policies reach them from the start.
• Device type: set the type, or leave it From the device.
• Display name: a pattern built from placeholders such as the customer and part of the serial number. Leave it empty to use the hostname.
• Note: shown beside each device waiting for approval.

To hold new devices by default on every new token, turn on Hold new devices for approval under Enrolment in Settings > Device lifecycle.

Approving held devices#

Devices > Enrolment, the Waiting for approval tab, lists each held device with its customer, serial number, IP address, the token and when it arrived.

• Approve lets it in, or approve it into another customer or site.
• Reject forgets the agent; that install cannot enrol again.

Each held device is also a request in the Approvals inbox, so it can be decided there or from the approval email.

Warning: The token is only shown once. Copy it now. You can always create another, and revoking a token does not affect devices already enrolled with it.

Run the install command#

Pick the tab for the machine's operating system and copy the command.

Within a few seconds the device appears under Devices with its hardware, operating system and the modules that are running. If the network is not ready when the service starts, the agent keeps retrying every minute until it enrols.

Tip: The same command works from your RMM, Intune or any MDM that can run a script, so you can roll the agent out to a whole customer at once with one token.

Installing the package yourself#

Deployment tools can install the signed Windows package directly, with the server and the token as installer settings:

msiexec /i tenvara-agent-<version>-x64.msi /qn TENVARA_SERVER=https://<your server> TENVARA_TOKEN=<token>

The settings are TENVARA_SERVER, TENVARA_TOKEN and, for an uninstall with tamper protection on, TENVARA_UNINSTALL_TOKEN. A command that names a setting any other way installs the agent without enrolling it, so copy the command again from the token or the Installers tab rather than reusing one you saved a while ago. Group Policy and Intune are covered step by step in Deploying the Windows agent with Group Policy or Intune.

Where the agent lives#

On Windows the agent installs to C:\Program Files\Tenvara\Agent, keeps its settings, keys and logs in C:\ProgramData\Tenvara\Agent and runs as the service TenvaraAgent. On Linux it is the package tenvara-agent, installed in /opt/tenvara/agent with its settings in /etc/tenvara/agent, running as tenvara-agent.service. See Agent names and folders, and Security software and the agent for what to allow in antivirus and EDR products.

Firewalls that inspect TLS#

Every connection the agent makes to your Tenvara server is checked against the certificate keys your server vouches for, not only against the certificate authorities the machine trusts. A firewall or secure web gateway that inspects TLS swaps the certificate, so the agent refuses to connect and its log says a TLS-intercepting proxy is in the way. Exclude your Tenvara server's name from inspection on networks that do this.

macOS permissions#

macOS only lets an app see the screen, control it, read the whole disk or update other apps once someone allows it in System Settings > Privacy & Security. The agent asks only for what the modules switched on for that Mac need:

Someone at the Mac allows each one in System Settings > Privacy & Security, where the agent appears in each list.

On the device page, a Mac has a macOS permissions card showing each one as granted, missing or not needed, with what needs it and where to switch it on. See The device page.

Manage tokens#

Devices > Enrolment opens on the Enrolment tokens tab, which lists every token with its customer, site, the start of the token, its state and whether it holds new devices. Click a token to see how many devices have used it, when it expires and when it was last used.

• Filter by Customer or State (active, expired, revoked).
• Click Revoke on a token to stop it enrolling any more devices. Devices already enrolled keep working.
• The Approval column shows whether a token holds new devices and how many are waiting, and Refused counts machines turned away as unsupported.

Reinstalls and changed hardware#

Each device has a fingerprint made from stable hardware identifiers, so reinstalling the agent on the same machine keeps the same device record and its history. When a new agent enrols:

• it is matched to an existing device by serial number first, then by hostname (never across customers), so a device you added by hand or that another source already reported is joined up rather than duplicated. A retired device is never matched: a machine that comes back after being retired arrives as a new device;
• if a device that already has a live agent is enrolled again with a different key, the new install is held as pending until an administrator approves it. This stops anyone who can read a machine's hardware IDs from taking the device over.

Moving a running agent to another server or token#

Running the install command again with another server or another enrolment token on a machine whose agent is already running moves it at once: the agent enrols with the new server or token without a restart and without uninstalling first. Use this to move a device to another customer's token or to a new Tenvara address.

Installers#

Devices > Enrolment, the Installers tab, lists the newest signed agent package for each platform, for use with software deployment tools: the Windows Installer package (for Intune, Group Policy or a double-click), the macOS package and the Linux packages.

• Get an install command opens the same dialog as Add devices.
• Older Windows (Lite agent) has the Lite agent's MSI and exe installer for 64-bit and 32-bit Windows, with the commands to install them and a note on the update Windows 7 and Server 2008 R2 need to check the signature. See Older Windows and the Lite agent.
• Release history lists every package on your server with its platform, architecture, package type, channel and size. Upload a package is there for servers without internet access.

Packages in a customer's brand#

Each customer's devices wear the brand profile the customer is assigned: its name in Apps and features, the tray, the consent prompt and the indicator people see during a remote session. Under Packages for a customer, choose a customer to get packages in their brand.

• Windows: the Signed MSI unchanged, the Brand transform (MST) that puts the brand on at install time, and a Bundle (ZIP) with both and an install script. Deployment tools install the MSI with the transform.
• macOS: the Signed pkg and a Brand file to place before the package when you deploy through an MDM.
• Linux: the Archive and its Brand file, which the one-line installer places for you.

The one-line install command from an enrolment token already includes the customer's brand. The signed packages themselves never change, and agents already installed pick up a change to the brand by themselves, without a reinstall. See Branded agent and installers.

Agent updates#

Agents update themselves. New releases arrive from the release feed, are checked and signed again by your server, and roll out to a pilot group first and then to everyone else after a soak. Each agent checks every update before it installs it, and an update that does not start is rolled back to the previous version. Updates never start during a remote session or a backup.

Channels, pins, maintenance windows and the pilot are covered in Agent updates and release channels. You can turn automatic updates off, and change how often agents check in, under Settings > Devices and agent. See Devices and agent settings.

Removing the agent#

When a machine leaves service, retire it with Retire device... from its ... menu: Tenvara can uninstall the agent for you the next time it is online. Delete device removes the agent too, unless you choose Keep the agent, just remove it from the list. A deleted device's agent cannot come back with the old token: enrolling the machine again needs a new one. See Deleting a device removes its agent. See Device lifecycle, retire, replace and stale devices.

To stop a device reporting without retiring it, open it and choose Revoke agent from the ... menu. The device record and its history stay in Tenvara; the agent is disconnected and can no longer sign in. A revoked device can be enrolled again later with a valid token.

To uninstall the agent from the machine itself, use Apps and features on Windows, the uninstaller on macOS or the package manager on Linux. With tamper protection on, the uninstaller asks for the customer's uninstall token. An agent update is never treated as a removal. See Tamper protection.