Client install

The Adaptiva Client must be installed on every device that will be managed. The Adaptiva Client supports a manual installation or a silent unattended installation. For complete coverage, the client agent setup can be added to a GPO-enforced startup script, the OS deployment process, and deployed using the peer-to-peer MSI.

Client Installation Files

You can find the Adaptiva Client installation media in the Installers folder of the compressed build files. For more information on the supported operating systems, see Supported Systems.

Windows installers

• adaptiva-client-<version>-windows.exe - Windows client full installer.

• adaptiva-client-<version>-x86-windows.exe - Windows 32-bit client installer.

• adaptiva-client-p2p-<version>-windows.msi - Windows Installer-based application. The P2P Installer first attempts to find the Windows client installer on the local subnet, then downloads from the specified location.

Cross-platform installers

• adaptiva-client-<version>-amd64.deb - Debian and Ubuntu installation packages.

• adaptiva-client-<version>-1.el8.x86_64.rpm - AlmaLinux 8, Oracle Linux 8, Red Hat Enterprise Linux 8 and Rocky Linux 8 installation packages.

• adaptiva-client-<version>-1.el9.x86_64.rpm - AlmaLinux 9, CentOS Stream 9, Oracle Linux 9, Red Hat Enterprise Linux 9, and Rocky Linux 9 installation packages.

• adaptiva-client-<version>-1.el10.x86_64.rpm - AlmaLinux 10, CentOS Stream 10, Oracle Linux 10, Red Hat Enterprise Linux 10, and Rocky Linux 10 installation packages.

• adaptiva-client-<version>-macOS.pkg - MacOS installation package client installer.

Note

The <version> represents the version number, which changes with each build release.

Client installation logs

In the case where an administrator needs to troubleshoot an Adaptiva Client installation, the table below contains the installation log locations. Other logs exist in the installation folder.

Windows client setup logs

• Standard client installation: %windir%\AdaptivaSetupLogs\Client\AdaptivaClientSetup.log

• P2P MSI client installation: %windir%\AdaptivaSetupLogs\Client\AdaptivaP2PClientSetup.log

• Client logs: %ADAPTIVACLIENT\logs\*\*.log

Mac adaptiva log

• Client installation log: /opt/adaptivaclient/logs/adaptiva.log

• Client logs: /opt/adaptiva/adaptivaclient/logs

Linux logs

Run the following command to view the client service log:

  sudo journalctl -u adaptivaclientd.service > .\AdaptivaClientdService.log

• Client logs: /opt/adaptiva/adaptivaclient/logs

NOTE: When sharing log files with Adaptiva Support, copy the Logs folder and then zip this folder to share your log files your support agent.

Windows client (full installer) setup

Manual full client installation

Use this method on a one-off basis during testing, initial rollout or to supplement automatic deployment.

1. Run the adaptiva-client-<version>-windows.exe as Administrator, found in the installation source folder..

2. In the Adaptiva Client Installer dialog, verify or change the following installation options.

   

Client Install Path Directory where the client will be installed.

Server Host Name or IP Address The fully qualified domain name or IP address of the Adaptiva Server.

Use Cloud Relay Service to connect when off-premises Check this box if clients will be on the internet or split-tunnel networks

Use Password for installation (optional) Check this box and enter the password provided by your OneSite Administrator.

Note: You can find the password in the Admin Portal under Settings | Client Authorization.

Server’s GUID (optional) Enter the Server GUID provided by your OneSite Administrator.

Note: You can find the Server GUID in the Admin Portal under Settings | Server Activation.

Enable Wake On LAN Allows the client to be woken up using peer-to-peer WOL.

Add/Remove Programs Entry Adds an entry allowing for uninstallation of the client agent from the Control Panel.

Add Windows Firewall Exception Adds exceptions to the local Windows Firewall for the default client ports, see Platform Communication Ports for a list of these ports.

Memory Sets the memory allowance for the client, in increments of 128 MB, with a minimum of 256 MB.

MSP Tenant Installation Only check this box if you are using a Managed Service Provider license and supply the Tenant GUID.

1. Click Install. The client is installed and then the installer runs the Adaptiva Client Validator.

Adaptiva Client Validator

The Adaptiva Client Validator verifies the connectivity requirements for the client.

If all checks pass (or are not applicable), then the client is fully online and ready to be managed. If any of the checks fail, you can make the appropriate firewall or network configurations and then rerun the Client Validator tool from the Adaptiva client installation location (%ADAPTIVACLIENT%\bin\AdaptivaClientValidator.exe).

Validation check detail

The following describes the validation checks being performed:

• HTTP Connection: Verifies the client can connect with cloud services.

• Cloud Relay Connection: Verifies the client can connect to the cloud relay system. The Adaptiva Server must be activated for this check to pass.

• Client-Server Messaging: Verifies the client can send and receive messages to the Adaptiva Server.

• Client-Server Handshake: Verifies the client can successfully perform a handshake with the Adaptiva Server and has obtained a client id.

• Client to Client: Checks if the client has peers in the office and verifies connectivity with those clients. Content Download: Verifies that the client can download a sample package of 8 bytes.

Unattended Installation EXE Command Line Parameters

In some cases, an administrator may want to use an unattended method to install the Adaptiva Client. The table below describes the command line parameters available for the Windows client installer.

Peer-to-Peer (P2P) MSI

The Adaptiva Client P2P MSI installer reduces the bandwidth required for the distribution of the Adaptiva agent. Using the Adaptiva Client P2P MSI installer, the Adaptiva Client can be pushed using a group policy, a startup script, SysInternals psexec, or any other remote execution method available.

Once executed, the Adaptiva P2P Client MSI installs the full Adaptiva Client. The MSI does not contain the full client installation. Instead, the MSI -- which is specific to a particular version of the Adaptiva Client agent -- first looks for the Adaptiva Client on a peer system in the same subnet with the correct version. If a device is found with the correct version, it retrieves the setup executable adaptiva-client-<version>-windows.exe from that local client and installs the Adaptiva Client from that executable. If a peer is not found with the correct version, the MSI retrieves the executable adaptiva-client-<version>-windows.exe from a UNC or URL path specified on the command line. If multiple systems run the MSI simultaneously and none of them find the correct version of the client locally, an election takes place among those clients. Only the winner of the election downloads the executable from UNC or URL path, and it then makes the executable available to the other client systems.

Note

Ensure that the installation account executing the MSI has read and execute access at the destination UNC path.

The Adaptiva P2P Client MSI can be used interactively or as a silent installer with no user interaction.

The P2P installer is named adaptiva-client-p2p-<version>-windows.msi and is in the compressed .zip product download source.

Important

The SaaS tenant provides a pre-configured Windows installer script. This script contains the necessary information to connect to the Adaptiva Tenant. When using the p2p installer for a self-hosted environment, use one of the following methods.

Manual Peer-to-Peer (P2P) client installation

1. Locate the adaptiva-client-p2p-<version>-windows.msi executable file on your machine and double-click it to execute.

   • The Adaptiva Peer To Peer Client Installer Setup dialog appears:

   
2. Select Next to initiate the setup.

   • The Install, update, clean, or remove installation dialog appears:

   
3. Select Install or Upgrade.

   • The Ready to Install or Upgrade dialog appears:

   
4. Select Install or Upgrade, and then select Finish to exit the installer setup wizard.

The other options perform the following tasks:

• Update: Upgrades the existing client to the version of the p2p client installer.

• Clean: Uninstalls the existing client, and then installs the Windows client.

• Uninstall: Uninstalls the Windows client.

Unattended Installation MSI Command Line Parameters

The table below contains the MSI properties valid for the P2P client installer.

Note

Be sure to enter these properties on the command line as <PROPERTY>=<Value>.

Installation command line examples

To deploy the Adaptiva P2P Client Installer, the only file needed for the package source is adaptiva-client-p2p-<version>-windows.msi which can be found in the Adaptiva installation source. The adaptiva-client-<version>-windows.exe must be accessible from a Share or a URL.

• Install with Server Share Source:

  Copy

  msiexec.exe /I adaptiva-client-p2p-<version>-windows.msi /qn SERVERNAME=AdaptivaServer.domain.com SOURCEUNCPATH=\\ServerFQDN\AdaptivaClient\adaptiva-client-<version>-windows.exe WAITFORCOMPLETION=1

• Install with Cloud and Internet Source:

  Copy

  msiexec.exe /I Adaptiva-client-p2p-<version>-windows.msi /qn SERVERNAME=AdaptivaServer.domain.com SOURCEURLS=https://tiny.url/abcdefg CLOUDRELAY=1 SERVERGUID=abcdefgh-abcd-1234-efgh-abcdefghijkl WAITFORCOMPLETION=1

  Include the following switches as required if the Cloud Relay service or if HTTP client communications will be used:

  • Cloud Relay service: CLOUDRELAY=1, SERVERGUID=<GUID>, PASSWORD=<auth. Secret>

  • HTTP communications: SERVERURL=<ServerURL:port>

    Note

    You Server GUID can be found in the Admin Portal under Settings | Server Activation. You can also find it in the Adaptiva server registry, under HKLM\Software\Adaptiva\server\client_data_manager.server_guid

• Uninstall and leave the files in the AdaptivaCache folder:

  Copy

  msiexec.exe /I adaptiva-client-p2p-<version>-windows.msi /q UNINSTALL=1 NOCACHEDEL=1

  The uninstall command line uninstalls any version of the Adaptiva Client. Using the standard Windows Installer uninstall parameter (/x) only uninstalls the specific version of the Adaptiva Client corresponding to the version of the MSI -- the MSI packaged with each version of the product is specific to that client version.

Client Installation on Linux or MacOS

You can install the Adaptiva Client on Linux and MacOS by installing the appropriate package and running the adaptivactl setup command. The setup command will install the OneSite client, configure firewall rules, and run post-installation checks to ensure functionality. The setup progress will print to the terminal and exit with a 0 exit-code if successful. If the client setup fails for any reason, it will exit with a non-zero exit-code.

The adaptivactl setup command checks for port availability before client setup. If a firewall is detected, setup will create firewall rules using the appropriate application: ufw with the DEB package, firewalld with the RPM package, and socketfilterfw with the MacOS package.

The client will now run post-setup checks to confirm connectivity with the server and other services. The setup will wait for these checks to be completed. You can skip these checks using the --skip-connection-checks flag.

There are several different installation packages provided for cross-platform device installations. Be sure to use the correct one for your operating system. Locate the installers\cross-platform folder in the downloaded .zip file. Replace <version> with the appropriate version.

Note

When installing the cross-platform client for the Adaptiva Cloud tenant, see SaaS Client Installation for more information.

Linux Installation

1. Open a terminal window and run the following command to execute the package:

• Alma, CentOS, Oracle, RHEL, Rocky

  Copy

  sudo dnf install ./adaptiva-client-<version>-1.el<#>.x86_64.rpm

• Debian, Ubuntu

  Copy

  sudo apt install ./adaptiva-client-<version>-amd64.deb

  Note When running the apt install interactively, the following message may be returned: N: Download is performed unsandboxed as root as file ‘/<path-to-install-package>’ couldn’t be accessed by user ‘_apt’. – pkgAcquire::Run (13: Permission denied) 109 You may ignore this error.

1. Run the following adaptivactl command in setup mode to configure the client:

sudo /opt/adaptiva/adaptivaclient/bin/adaptivactl setup <flags>

Only the --server flag is required. See the table below for the available parameters.

Example:

sudo /opt/adaptiva/adaptivaclient/bin/adaptivactl setup --server adaptivaserver.corp.example

1. Once the client installation is completed, the client will perform a series of connection checks.

[info] Running connection checks…
[info] The connection check ‘HTTP Connection’ has started
[info] The connection check ‘HTTP Connection’ has passed
…

1. When the connection checks are completed, the Patch Client is fully online and ready to be managed.

MacOS Installation

1. Open a Command terminal window, then run the following command to execute the package:

sudo installer -tgt / -pkg ./adaptiva-client-<version>-macOS.pkg`

1. Run the following adaptivactl command in setup mode to configure the client:

sudo /opt/adaptiva/adaptivaclient/bin/adaptivactl setup <flags>`

Only the --server flag is required. See the table below for the available parameters.

1. Once the client installation is completed, the client will perform a series of connection checks.

[info] Running connection checks…
[info] The connection check ‘HTTP Connection’ has started
[info] The connection check ‘HTTP Connection’ has passed
…

adaptivactl command line parameters

A list of the command line parameters for the adaptivactl, both required and optional. Known flags can also be printed by running:

/opt/adaptiva/adaptivaclient/bin/adaptivactl setup --help

Examples:

Direct server using an IP address, an HTTP proxy, and a custom system config:

sudo /opt/adaptiva/adaptivaclient/bin/adaptivactl setup --server 198.50.100.241 --server-guid 1cb07a9e-a88c-4db2-8fe3-2eb7748545d6 --proxy http://198.50.100.3:8080 --system-config onesite.server_message_retry_interval=60

Server using cloud relay, hostname, client authentication:

sudo /opt/adaptiva/adaptivaclient/bin/adaptivactl setup --server adaptivaserver.corp.example --server-guid 1cb07a9e-a88c-4db2-8fe3-2eb7748545d6 --auth-secret 'P@ssw0rd123!'

Modify system configuration

The adaptivactl command can also be used to read and write system config values using the config operation.

The following command reads the value of a system config property:

sudo /opt/adaptiva/adaptivaclient/bin/adaptivactl config get <property>

The following command sets the value of a system config property:

sudo /opt/adaptiva/adaptivaclient/bin/adaptivactl config set <property> <value>

Cross Platform Upgrade

If you need to upgrade existing cross-platform clients to a newer version manually, perform package upgrades using the commands below. For more information on the supported operating systems, see Supported Systems.

Debian / Ubuntu:

sudo apt install ./adaptiva-client-<version>-amd64.deb

AlmaLinux, CentOS Stream, Oracle, RHEL, Rocky

sudo dnf upgrade ./adaptiva-client-<version>.el<#>.x86_64.rpm

macOS:

sudo installer -tgt / -pkg ./adaptiva-client-<version>-macOS.pkg

Note Due to an issue in the 9.2.967 RPM packages, upgrading from 9.2.967 to 9.3.968 or later requires the following commands: sudo dnf upgrade ./adaptiva-client-9.3.968.19-1.el9.x86_64.rpm sudo systemctl enable --now adaptivaclientd.service

SaaS Client Installation

Log in to https://console.adaptiva.cloud and click Go to Cloud Portal. Under My Tenants, on your tenant details click Manage.

In the Tenant Client Downloads section, click the download button () next to the desired OS option. Administrators may reset the Client Authorization token to prevent previously downloaded installers from connecting to the Adaptiva Server. Clients already installed are not affected when resetting the Authorization token.

Install the Windows SaaS Client

The Adaptiva Windows Client is installed using the P2P installer with all the needed configuration parameters in an .msi file.

1. Select the Windows Client from the dropdown menu.

2. Select to download the installer to your machine.

3. Run the downloaded .msi file, and then the client will be installed.

Install the Cross Platform SaaS Client

The Cross Platform Adaptiva Client is installed using a shell script.

1. Select the appropriate Linux or macOS Client from the dropdown menus.

2. Select to download the .sh shell script to your machine.

3. Open a Command terminal window, then run the command below to execute the package. This command automatically downloads the appropriate package and installs the client.

sudo bash adaptiva-client-<version>-install-unix-<tenantObjectID>.sh

Note When running the shell script interactively on systems that use apt, the system may return the following message: N: Download is performed unsandboxed as root as file ‘/<path-to-install-package>’ couldn’t be accessed by user ‘_apt’. – pkgAcquire::Run (13: Permission denied) 109 You may ignore this error.