How to Connect Servers Using the SnapShooter Agent

SnapShooter is a cloud backup and recovery solution. Use SnapShooter to back up servers, volumes, databases, and applications from DigitalOcean and other cloud providers.

The SnapShooter Agent allows SnapShooter to communicate with private resources that are behind a NAT gateway or firewall. Using the agent also eliminates the need to configure firewalls, incoming connection rules, or IP allowlists.

The agent works by opening a persistent communication channel from the target resource back to the SnapShooter network. The resulting backups are identical to backups taken with an SSH-based connection.

Supported Environments

The SnapShooter Agent supports the following architectures:

  • x86 (386)
  • x86 64-bit (amd64)
  • ARM (arm)
  • ARM 64-bit (arm64)

The agent runs on the following operating systems:

  • Linux (linux)
  • OpenBSD (openbsd)
  • FreeBSD (freebsd)
  • NetBSD (netbsd)
  • macOS (darwin)

Software Prerequisites

The following tools are required to install the SnapShooter Agent:

  • bash
  • curl
  • gzip
  • tar

These are available for every supported operating system, but may not be installed by default. Verify that they are installed or install them via your operating system’s package manager:

# Using APT
apt-get install curl gzip tar

# Using YUM
yum install curl gzip tar

# Using DNF
dnf install curl gzip tar

# Using Pacman
pacman -Syu curl gzip tar

# Using APK
apk add curl gzip tar

Install the Agent

There are two ways to install the SnapShooter Agent: by using our automatic installation script, or by manually downloading and installing the agent.

To use the automatic installation script, first open the Create an Agent Setup Token page. Name your token and click the Create Setup Token button.

Find your token in the Active Setup Tokens list and click its Show Setup Script button. Copy the displayed script, which is similar to the following:

bash <(curl -sSL '274|yHrIPApr2rb5fcweECX72tG186SPVNPeAxCv5vjl'

Log in to your server’s command line as the root user and paste the script, then press Enter to run the script.

When the script exits, verify the service has been installed, enabled, and activated using systemctl:

systemctl status snapshooter
● snapshooter.service - SnapShooter agent
     Loaded: loaded (/etc/systemd/system/snapshooter.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2023-10-16 16:45:15 UTC; 8s ago
   Main PID: 216026 (agent)
      Tasks: 7 (limit: 9478)
     Memory: 5.8M
        CPU: 20ms
     CGroup: /system.slice/snapshooter.service
             └─216026 /opt/snapshooter/agent

Oct 16 16:45:15 builder systemd[1]: Started SnapShooter agent.

The output indicates that the service is active and running. Go to the Agent Servers page to verify the new server is listed and online:

screenshot of the Agent Servers dashboard page, showing a list of 1 server, with columns of name, registered date, and action buttons to view, edit, and delete

If you prefer not to run the automated installation script, you can manually download and install the agent.

First, go to the Manually Add an Agent Server page.

Name your server and click Generate Agent Server Token.

Select the target operating system and architecture of your resource. This generates the correct download URL. Copy the URL to your clipboard.

Log in to your server’s command line as the root user and use curl to download the agent:

curl -sSL <generated download url> -o agent.gz

Substitute <generated download url> with the URL you copied from the dashboard. curl downloads the file to agent.gz in your current directory. Decompress the downloaded file:

gzip -d agent.gz

You can store the agent binary in any directory. We recommend keeping all SnapShooter-related installations under /opt/snapshooter:

mkdir -p /opt/snapshooter
mv ./agent /opt/snapshooter/
chmod +x /opt/snapshooter/agent

This creates the target directory, moves the binary file into it, and sets the file as executable.

The SnapShooter Agent needs a token to authenticate and identify itself. The token is shown as the SNAPSHOOTER_AGENT_TOKEN environment variable in the command at the bottom of the page.

You can pass this token to the SnapShooter Agent in two ways:

  1. From a file named agent.conf, which must be available in the same directory as the agent binary file:
echo '<your-token>' > /opt/snapshooter/agent.conf
  1. As the SNAPSHOOTER_AGENT_TOKEN environment variable. One method for passing this variable to the agent is shown in the generated dashboard script:
SNAPSHOOTER_AGENT_TOKEN='314|evmyXom7OZtC6yhw7tAsWfFf9cQnpYASyjFSHsaE' ./agent-linux-amd64

SnapShooter services only allow up to 1 connection per token, so you can only run one instance of a SnapShooter Agent with a given token. All other connections are dropped immediately.

You can manage the execution of the SnapShooter Agent like any other process. For example, you can run it as an always-on systemd service, use a tool like Supervisor to keep your service running in the background, or run it in a detached terminal using tmux.

By default, if the SnapShooter Agent disconnects from SnapShooter’s network, it tries to reconnect automatically. However, using a process manager ensures that the process is always running, even after software updates and server reboots.

Uninstall the Agent

To uninstall the agent, deactivate its service and delete the relevant files.

First verify that you no longer have any backup jobs configured using your SnapShooter Agent. You can check this by going to your SnapShooter Agent Servers Dashboard. Locate and open your SnapShooter Agent and ensure that no backup jobs are listed for this server.

You can either remove the backup jobs entirely, or assign them to another resource.

Next, check if the SnapShooter Agent is running as a service using systemd or another tool like Supervisor, then disable and stop its execution. For the systemd service installed by the automatic installation script, use systemctl:

systemctl stop snapshooter
systemctl disable snapshooter
rm /etc/systemd/system/snapshooter.service

This stops and disables the service, then removes its systemd configuration file.

Now remove the contents of the installation directory. If you used the automatic installation script, the SnapShooter Agent configuration files and binaries are located in /opt/snapshooter:

rm -rf /opt/snapshooter

Remove the SnapShooter Agent from the SnapShooter Agent Servers Dashboard. This can be done by opening your SnapShooter Agent and then pressing Delete.