Install the Agent from the command line

The Agent provides command-line arguments to support automated installation. To install Agents in this manner, download a generic Agent installation package from the Downloads page of the Connected web application. Then, create a custom process that distributes and installs it on multiple devices at the same time. After installation completes, the Agent automatically prompts for the user's Connected email address. In environments with federated authentication, the Agent then automatically signs the user on. Otherwise, it also prompts for the user's credentials or to select the appropriate authentication certificate. After authenticating the user, the Agent starts to process files on the computer.

Before you begin

Before you install Agents using this procedure, do the following:

• Create users, for the Agents you plan to install.
• Verify that all target computers meet Agent requirements.

To install the Agent from the command line

1. In the upper-right corner of the web application, click your name, and then click Downloads.

2. Under Download a Specific Agent on the Downloads page, select a specific Agent, and then download it.

   You can choose any Agent version currently available to your company.

3. Install the new Agent using the appropriate command for the target operating system.

   You can automate the process for deployment to multiple Agents by specifying the command in a custom script or software deployment tool or you can install the Agent on the current computer by typing the command at a Terminal or Command Prompt.

   • On Windows-based computers, use the msiexec command. See example.

     To run the command in a Command Prompt window

     1. Open a Command Prompt window, and then change directory to the location where you saved the package.

     2. At the command prompt, enter the Msiexec.exe command that you want to use.

        For example, to install the Agent assigned to the US-West data center, enter the following command: msiexec /qn /i ConnectedSetupUSW64.msi

     3. If prompted, restart the computer to complete the installation.

        If the installation process cannot completely install or configure a component in use by another application, it prompts you to restart the computer. After restart, the installation process automatically completes.

     For the complete command-line syntax and examples, see Agent installer command-line reference (Windows).

   • On macOS-based computers, use the installer command. See example.

     To run the command in a Terminal prompt

     1. Open Terminal, and then change directory to the location where you saved the package.

     2. At the Terminal prompt, enter the sudo command that you want to use.

        For example, to install the Agent assigned to the US-West data center, enter the following command: sudo installer –pkg ConnectedSetupUSW.pkg -target /

     IMPORTANT: macOS 10.15 (Catalina) introduced data protection measures on folders that contain your documents and other personal files in your user profile. As a result, the first time the Agent attempts to access a file in each of these folders, macOS prompts whether to allow access.

     The first of these prompts occurs during Agent installation or upgrade to macOS Catalina when the installation package tries to create a shortcut on the desktop. Additional prompts occur during the Agent’s initial scan whenever it attempts to access one of the protected folders for the first time. For the Agent to back up files, the user must allow access. After granting access to a specific folder, the user is not prompted again for that location unless they manually revoke access through the macOS Security & Privacy settings.

     For more information about this macOS security-related data protection feature, see https://www.apple.com/macos/catalina/features/.

     For the complete command-line syntax and examples, see Agent installer command-line reference (macOS).

4. If your company uses certificate-based authentication and this is the initial installation of the Agent on the computer, add commands to distribute and install the authentication certificate.

5. If your company manages its own encryption keys and this is the initial installation of the Agent on the computer, distribute and install the Connected device client certificate.

   The Agent requires this certificate to establish a secure connection to Connected Key Management Server. Without it, the Agent will not work correctly. Distribute and install the certificate manually, or if using a custom script or deployment tool to automate the installation process, update it to perform these tasks for you. For more information, see Install the Connected device client certificate.

6. If automating the installation using a custom script or software deployment tool, initiate Agent deployment now using your script or tool.

If the installation fails, see the FAQ The Agent install or upgrade process failed, what should I do? for troubleshooting tips.

After a successful installation, the following occurs:

• On Windows-based computers:

  • If you used the /qn option to install the Agent silently, the user must start the Agent manually.

  • If you did not use the /qn option, the Agent starts automatically unless the wizard's Launch Connected check box was cleared. In that case, the user must start the Agent manually.

• On macOS-based computers, the Agent starts automatically.

When the Agent starts for the first time, it prompts for the email address associated with the user's Connected profile that you created for them. In environments with federated authentication the Agent then automatically signs the user in. Otherwise, the user must enter the credentials associated with their Connected profile or select the appropriate authentication certificate. After sign in, the Agent displays the Device Setup Wizard page for the user to complete the Agent setup.

If installing the Agent for yourself, in response to the wizard's prompt for how to configure the computer, select either As a replacement or reinstallation of my existing computer (also applies to simply reinstalling the Agent) or As a secondary or additional computer. Then, click Finish.