Managing Agents

An Agent is a lightweight service that connects to your configured storage, providing direct access to scan and move data. Agents are compatible with various storage types, including local file systems, network file shares, and object storage. They handle tasks like discovering data, analyzing file structures, and transferring files between sources and destinations.

Each Agent communicates with the CloudSoda Controller using UDP ports 7498 and 7499. If your environment includes multiple firewalls, be sure traffic can pass through all of them, not just the one closest to the Agent.

Use the following procedures to manage Agents:

• Creating an Agent
• Downloading the Agent Configuration
• Installing the Agent
• Uninstalling an Agent

Creating an Agent

To create an Agent, follow these steps:

1. Click Orchestration > Agents in the left-hand navigation panel.
   The Agents page displays.
   
   
2. Click Create Agent.
   The Create Agent page displays.
   
   
3. Enter the Agent data: 
   
   • Name: Enter a name for the Agent.
   • Account: Select an account associated with the Agent.
   • Scope: Initial scope on the Agent which configures access control.
4. Toggle Transient if the Agent should operate as a transient Agent.
   
   
5. Click Add Tags to assign tags to objects moved by the Agent; this is optional.
   The Add Tag window displays.
   
   a. Enter a Key and Value for the tag. 
   b. Click Save to apply the tag.
   
   
6. Select a Location for the Agent. If you choose a cloud provider, you'll also need to select a region. If you select Other, you can specify a country to indicate where the Agent is located.
   
   
7. Click Save to create the Agent.
   The Agents page displays the newly created Agent in the list. 

Downloading the Agent Configuration

1. Click Orchestration > Agents in the left-hand navigation panel.
   The Agents page displays.
   
2. Click Download Agent and select an operating system::
   • Linux/macOS - download a tar file of the Agent Installer software.
   • Windows - download a Windows zip file of the Agent Installer software.
     
     
3. Extract the downloaded file:
   • Linux/macOS - Untar the file to the /tmp folder or another directory on your Linux or Mac client.
     
   • Windows - Unzip the file to the Downloads folder or another directory on your Windows client.
     
     
4. In the CloudSoda UI, navigate to the Agents page and select the newly-created Agent.
   The Agent page displays and and defaults to the Details tab.
   
   
5. Click the ellipsis (…) at the top-right of the page and Download Config to download a JSON file for the Agent configuration. Be sure this file is located in the same directory as the Agent Installer.

Installing the Agent

To install the Agent, follow the procedure for your operating system: 

• Installing the Agent on Linux/macOS
• Installing the Agent on Windows

Installing the Agent on Linux/macOS

To install the Agent on Linux or macOS, follow these steps:

1. Run as root or sudo.
   
2. Enter the following commands:
   

   echo $PATH as root and verify that /usr/local/bin is in the PATH
   cd /tmp (or wherever you put the files)
   tar -xvf soda_*.tar
   chmod +x soda
   sudo xattr -d com.apple.quarantine ./soda #run on macOS ONLY
   sudo ./soda install
   sudo soda status
   sudo soda help (to view all command options)
   

   NOTE: If you receive a pop-up with this message: "Soda' can't be opened because Apple cannot check it for malicious software", refer to the macOS Troubleshooting section below.
   
   
3. To enable full disk access for CloudSoda on macOS to CloudSoda, follow these steps:
   1. Open System Settings.
   2. Click Privacy & Security.
   3. Click Full Disk Access.
   4. Click the + icon at the bottom and enter your password when prompted.
   5. Press Shift+Cmd+G simultaneously, then press Enter.
   6. Scroll and select soda from the list, then click Open.

Once the Agent is installed, check its status:

• If soda status confirms it is running, return to the CloudSoda UI to enable the Agent.
  
• In the Agent Show model, click on the ellipses (…) and select Enable. You can also enable the Agent from the Agent page by clicking the > icon. 

Completing this process securely configures and authenticates the Agent, connects it to the CloudSoda Controller, and assigns it to the appropriate storage. 

If the Agent appears to be disconnected, refer to Why won't my Agent connect?

Installing the Agent on Windows

You can install the CloudSoda Agent on Windows using one of two methods:

• PowerShell (Administrator) - recommended for most users
  Installs method installs the Agent as a background service that runs continuously. However, because the Agent runs under the a local administrator account, it may have trouble accessing remote shares that require specific user credentials, e.g. username and password as a local mount. In these cases, use the SMB accessor when trying to access SMB shares instead of the File accessor with a file path to the local mount.
  
  
• PowerShell (Logged-in User)
  This method installs the Agent to run in your System Tray, operating only under your logged-in user session. The Agent will start and connect only when you are logged in and does not run as a persistent background service. 

To install the Agent on Windows, follow these steps:

1. Open the Windows PowerShell (Admin) or PowerShell based on your chosen installation method.
   
   
2. Enter the following commands:

   ./soda.exe install
   Install CloudSoda? [Y/N] y
   Installing binary...
   Profile file: agent-config.json
   Setting up C:\ProgramData\soda... [etc.]
   soda status
   soda help (to view all command options)

    
3. If soda status confirms the Agent is running, return to the CloudSoda UI to enable it. 
   
   
4. In the Agent Show model, click on the ellipses (…) and select Enable from the drop-down. You can also enable the Agent from the Agent page by clicking on the > icon. 

Completing this process securely configures and authenticates the Agent, connects it to the CloudSoda Controller, and assigns it to the appropriate storage. 

If the Agent appears to be disconnected, refer to Why won't my Agent connect?

macOS Troubleshooting

If you encounter issues installing the Agent on macOS, try this troubleshooting procedure before contacting CloudSoda Support.

Agent Won't Run Due to Security Restrictions

If you see the error "soda' can't be opened because Apple cannot check it for malicious software", follow these steps before re-trying the installation procedure:

1. Open System Settings > Privacy & Security.
   The Privacy & Security window opens.
   
   
2. Click the Privacy & Security icon.
   
   The Privacy & Security window opens.
   
   
   
3. Click the lock at the bottom-left of the window.
   The System Preferences window opens.
   
   
4. Enter your password in the appropriate field.
   
   
5. Click the Unlock button.
   You return to the Security & Privacy window.
   
   
6. Click the Allow Anyway button.
   
   
7. Close the Privacy & Security window.
   
   
8. Re-enter the ./soda install command.
   The error pop-up window reappears.
   
   
   
9. When prompted, enter your Mac administrator password and click Open.
   The window closes, and the soda installation continues.
   

Return to Step 3 of the Installing the Agent on Linux/macOS procedure above to complete the installation.

Uninstalling an Agent

Uninstalling an Agent is a two-step process. First, detach the Agent from all attached storages and then uninstall it from CloudSoda. Next, uninstall CloudSoda from the Agent's host.

Uninstall the Agent from CloudSoda

To uninstall an Agent, follow these steps:

1. Click Orchestration > Agents in the left-hand navigation panel.
   The Agents page displays. 
   
   
2. Click the Agent you to want to uninstall.
   The selected Agent's dialog box displays and defaults to the Details tab.
   
   
3. Click the Attachments tab to display all storages attached to the Agent. Before uninstalling the Agent, make sure all attached storage is detached.
   
   
4. To detach a storage:
   1. In the row for the storage you want to detach, click the Disable icon on the right side and then click the Delete icon. The selected storage is detached from the Agent.
   2. Repeat this step for all storages attached to the Agent.
      
      
5. Click the ellipses (...) at the top right of the Agent's dialog box and select the Delete option to uninstall the Agent.

Once the Agent is uninstalled, it will no longer be available, but CloudSoda remains installed on the Agent's host. To fully remove CloudSoda from the host, use this procedure. 

Uninstall CloudSoda from the Agent's Host

To uninstall CloudSoda from the Agent's host, follow these steps:

1. From a command prompt, run the following command:
   
   macOS/Linux Example:
   

   sudo soda uninstall 

   
   Windows Example:

   soda.exe uninstall
   

    
2. Navigate to the following directories and delete the contents to fully remove CloudSoda from the server:
   
   macOS/Linux directories:
   

   /usr/local/bin/soda
   /etc/soda/* (plus the directory)

   
   Windows directories:

   /soda/*
   /soda/* 

CloudSoda has now been uninstalled and removed from the Agent's host.