Change, upgrade, or uninstall Workstation Agent

After you install the Workstation Agent, you change its settings and its authorization file on each machine, and you upgrade or remove it the same way you installed it. Most of what the agent monitors comes from OpenLM Platform, through Agents Hub.

Change the agent settings

The Workstation Agent reads its settings from settings.json, and its authorization details from agent-authorization.json, in the installation folder:

• Windows: C:\Program Files\OpenLM\Agent\. Edit the files as an administrator.
• Linux: /opt/openlmagent/.
• macOS: /Library/OpenLMAgent/.

The agent reads both files when it starts. After you change a file, restart the agent:

• Windows: sign out of Windows and sign in again. Or end OpenLM.Agent.Windows.Core.exe in Task Manager, and then select Start OpenLM Agent in the Start menu.
• Linux: run systemctl --user restart openlmagent as each signed-in user.
• macOS: run launchctl kickstart -k "gui/$(id -u)/com.openlm.agent" as each signed-in user.

In settings.json, the setting you change most often is logging.minimumLevel, the level of detail of the agent log. Its values are Verbose, Debug, Information (the default), Warning, Error, and Fatal.

Give the agent a new authorization file

The Workstation Agent needs a new authorization file when you reset the secret of its client in Identity, or delete the client and generate a file for a new one. Until it gets the new file, the agent can't connect to OpenLM Platform.

To give an installed agent a new authorization file:

1. Generate the file for a client of type Agent in Identity, as described in Authorize components.
2. Replace agent-authorization.json in the installation folder of the agent with the new file: C:\Program Files\OpenLM\Agent\ on Windows, /opt/openlmagent/ on Linux, or /Library/OpenLMAgent/ on macOS.
3. Restart the agent, as described in Change the agent settings.

Upgrade the agent

To upgrade the Workstation Agent, install the version you upgrade to over the installed one. Use the method for your installation:

• Windows: run the MSI for the version you upgrade to. On the Upgrade Detected page, keep Upgrade using existing settings to keep the configuration, or select Customize configuration settings to go through the configuration pages again. A silent installation keeps the configuration. To install silently, run this command:

  msiexec /i "<msi-path>" /qn

• DEB package: run this command:

  sudo apt install ./openlm-agent_<version>_amd64.deb

• RPM package: run this command:

  sudo dnf upgrade ./openlm_agent-<version>.x86_64.rpm

• tar.gz archive: extract the archive for the version you upgrade to into a new, empty folder, and run this command from it:

  sudo bash install.sh

  The script keeps settings.json, agent-authorization.json, and the logs.

• macOS: install the package for the version you upgrade to. It keeps settings.json and agent-authorization.json.

In these commands, replace <msi-path> with the full path of the MSI file, and <version> with the version you upgrade to.

On Windows, an upgrade keeps the installation folder, settings.json, and the authorization file. It deletes the data the agent stored while it was offline, so let the agents connect and send their data before you upgrade. The installer doesn't install an older version over a newer one, and reports A newer version of OpenLM Agent is already installed.

On Linux, back up settings.json and agent-authorization.json before you upgrade with a package, and check them afterwards. The packages install their own copies of both files.

To upgrade Workstation Agents on Windows from OpenLM Platform, see Upgrade agents in Agent Activity. To upgrade them with a deployment tool, deploy the MSI for the version you upgrade to with the command in Deploy to many machines.

Uninstall the agent

Remove the Workstation Agent the same way you installed it:

• Windows: in the Control Panel, select Programs, then Uninstall a program. Select OpenLM Agent, then Uninstall. To uninstall silently, run this command with the installer you installed from:

  msiexec /x "<msi-path>" /qn

  Replace <msi-path> with the full path of the MSI file.

• DEB package: run this command:

  sudo apt remove openlm-agent

  Then run this command to clear the package record:

  sudo apt purge openlm-agent

• RPM package: run this command:

  sudo dnf remove openlm_agent

• tar.gz archive: run this command:

  sudo bash /opt/openlmagent/uninstall.sh

• macOS: run this command:

  sudo sh /Library/OpenLMAgent/uninstall.sh

  For more information, see Uninstall the agent.

On Windows, uninstalling stops the agent and removes the OpenLM Agent Updater Service, but keeps settings.json and the authorization file, agent-authorization.json, in C:\Program Files\OpenLM\Agent. To remove the agent completely, delete that folder after you uninstall, because the authorization file holds the credentials of the agent. The data and logs of each user stay in %APPDATA%\OpenLM\Agent, and those of the updater in %ProgramData%\OpenLM\Agent.

On Linux, removing the agent stops it for every user and deletes /opt/openlmagent, with settings.json, the authorization file, and the logs. The data the agent stored for each user stays in ~/.config/OpenLM/Agent.

Uninstalling leaves the agent listed in Agent Activity, where it shows as offline. To remove it there as well, see Remove agents.

Check the result

After you change a setting, give the agent a new file, or upgrade it, check that the agent reports:

1. In OpenLM Platform, open Navigation, select Agents, then Agent Activity, and select the Refresh icon.
2. Find the row with the host name of the machine. Online shows a check mark while the agent is connected, and Agent Version shows the installed version.

If the agent doesn't appear, see Troubleshoot Workstation Agent. To see what changed in each release, see the Workstation Agent changelog.

Next step

Select which applications the agent reports in Process Manager. Then continue the setup with Install the Directory Synchronization Agent (DSA).