____                   __     __     ___                    __
   / __ \_________  ____  / /__  / /_   /   | ____ ____  ____  / /_
  / / / / ___/ __ \/ __ \/ / _ \/ __/  / /| |/ __ `/ _ \/ __ \/ __/
 / /_/ / /  / /_/ / /_/ / /  __/ /_   / ___ / /_/ /  __/ / / / /_
/_____/_/   \____/ .___/_/\___/\__/  /_/  |_\__, /\___/_/ /_/\__/
                /_/                        /____/

Droplet Agent is the daemon that runs on DigitalOcean's customer droplets to enable some features such as web console access.

• Building
  • Building From Source Code
  • Packaging
• Running the Agent
• Running Tests
• Compatibility
• Contributing

Building

Building From Source Code

Clone this repository:

> git clone [email protected]:digitalocean/droplet-agent.git
> cd droplet-agent

To build the agent, do the following:

1. cd ./cmd/agent
2. GOOS=<target OS> go build -o droplet-agent

This will generate the droplet-agent binary.

Upload that binary to your droplet and run:

./droplet-agent -debug

The Droplet Agent should now be running on your droplet.

Packaging

We now support building deb and rpm packages. You are welcome to submit PRs for supporting other package management systems.

NOTES:

1. As of now, the only supported <target OS> is Linux, via deb and rpm
2. The only supported GOARCH is amd64
3. systemd is required for service management, automatic package updates, and install retries
4. The agent service unit is installed at /etc/systemd/system/droplet-agent.service. After editing it, run systemctl daemon-reload
5. Hourly package update checks are handled by droplet-agent-update.timer and droplet-agent-update.service in /etc/systemd/system/. The timer is enabled automatically on package install. After editing these units, run systemctl daemon-reload && systemctl enable --now droplet-agent-update.timer

Running the Agent

The agent binary takes several command line arguments:

• -debug (boolean), if provided, the agent will run in debug mode with verbose logging. This is useful when debugging.
• -syslog (boolean), specify how the log is handled. By default, all logs will be sent to stdout and stderr, if syslog option is provided, logs will be sent to syslogd. When logging to syslog, the agent will use DropletAgent as the identifier. To retrieve the logs, simply run journalctl -t DropletAgent command.
• -sshd_port <port>(integer), explicitly indicates which port sshd binds itself to, so that the agent can properly monitor the port knocking messages, as well as enabling the web console proxy to connect to the sshd instance. Without specifying this option, the agent will try parse sshd_config to see if custom port is specified by checking the Port and ListenAddress entries, if not, it falls to use the default port (22).
• -sshd_config <path to sshd_config> (string), explicitly specify the path to the sshd_config file. In the cases that the sshd is started with a custom sshd_config file other than the default one (/etc/ssh/sshd_config), this parameter must be supplied to let the agent function properly

NOTES:

• Be aware that sshd_port number has higher priority. The agent will skip attempting to parse the port from sshd_config if sshd_port is supplied.
• When parsing the sshd_config, the agent will take the first occurrence of port number from either Port or ListenAddress entries. If the sshd is configured to bind to multiple interfaces and/or multiple ports, please sepcify the port number that is exposed externally via sshd_port option.

Running Tests

First, ensure that Docker is installed and running.

Then, inside the droplet-agent project directory:

> go mod vendor
> make test

Compatibility

Droplet Agent currently supports:

• Ubuntu (oldest End Of Standard Support LTS release and later)
• Debian (oldest supported LTS release and later)
• Fedora 41+
• CentOS 9+
• AlmaLinux 8+
• Rocky Linux 8+

All supported distributions use systemd.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests.

"Droplet Agent" is copyright (c) 2021 DigitalOcean. All rights reserved.