Install the Agent

To install the Pro Custodibus agent on a Linux, FreeBSD, OpenBSD, or macOS host, make sure you have downloaded the host configuration files from the Host Setup page, and have downloaded the agent tarball from the Agent Downloads page.

To install the Pro Custodibus agent on a Windows host, download and run the Windows installer. To run the Pro Custodibus agent in a Docker (or other OCI) container, use a pre-built container image.

Extract the Tarball

Copy the agent tarball to the host and extract it. Run the following command in a terminal on the host:

$ tar xf procustodibus-agent-latest.tar.gz

This will extract the latest version of the agent to a directory called procustodibus-agent-1.0.0 (or whatever the actual latest version number is instead of 1.0.0).

Run the Installer

The installer must be run as root. After extracting the tarball, run the following commands in the terminal on the host to run the installer:

$ cd procustodibus-agent-*/
$ sudo ./install.sh --install
running as root
install 1.0.0
agent configuration found at /etc/wireguard/procustodibus.conf
agent setup found at /etc/wireguard/procustodibus-setup.conf
/etc/wireguard/procustodibus.conf mode ok (-rw-rw-r--)
WARNING /etc/wireguard/procustodibus.conf owner should be root
fix owner? ([y]es, [n]o): y
OK will fix owner
fixed owner
...
...
...
WARNING daemon dead
start daemon? ([y]es, [q]uit): y
OK will start daemon
Created symlink /etc/systemd/system/default.target.wants/procustodibus-agent.service → /etc/systemd/system/procustodibus-agent.service.
started daemon
install SUCCESS

Next Steps

  1. If you run into errors with the installer, check the Troubleshooting section of this page.

  2. Otherwise, check the host’s main page in the app. The Agent panel should show the results of the agent’s latest ping.

  3. If the Agent panel simply reads Set Up Agent, or if the Interfaces panel doesn’t list the WireGuard interfaces you already have running on the host, check the Agent Troubleshooting page.

Logging

In addition to writing output to stdout, the installer also writes similar output to a log file on the host, located here:

/var/log/procustodibus-install.log

You can refer to this log file to help determine what, where, and when the installer installed something on your host. Our support staff may also ask you to send us this log when we’re helping you troubleshoot installation issues.

Other Options

Run the installer with the --help flag to see the other installer options:

$ ./install.sh --help
Pro Custodibus Agent installer.

Installs the Pro Custodibus Agent as a daemon in a python virtualenv.

Usage:
  install.sh --help
  install.sh --dryrun [--install | --remove]
  install.sh --install [--force]
  install.sh --remove [--force]
  install.sh --version

Options:
  -h --help     Show this help
  -d --dryrun   Run all installer checks without installing/removing anything
  -f --force    Automatically answer yes to all prompts
  -i --install  Install the agent
  -r --remove   Remove the agent
  -v --version  Show version number

Environment variables:
  INSTALL_LOG       Path to installer log ('/var/log/procustodibus-install.log')
  INSTALL_PYTHON    Path to python executable ('python3')
  INSTALL_SRC       Path to agent source code ('/root/procustodibus-agent-1.0.0')
  INSTALL_VENV      Path to agent virtualenv ('/opt/venvs/procustodibus-agent')

Dryrun

Running the installer with the --dryrun flag will run through the installer steps without actually doing anything to your host. It will output lines beginning with ERROR, WARNING, or OK to indicate what it will or will not do:

  • ERROR to indicate a missing component that will block the installation (like a missing agent configuration file)

  • WARNING to indicate a missing component that the installer will install (like libsodium)

  • OK to indicate what the installer will do to install the missing component

You don’t have to run the installer as root for a dry run; however, the output may not be fully accurate unless you do.

$ ./install.sh --dryrun
WARNING not running as root: dryrun may be inaccurate
dryrun force install 1.0.0
ERROR agent configuration not found at /etc/wireguard/procustodibus.conf
please download procustodibus.conf and procustodibus-setup.conf from the host's setup page on https://pro.custodib.us/, and then re-run this script; see https://docs.procustodibus.com/agents/install/ for more info
ERROR agent credentials not found
please download procustodibus-setup.conf from the host's setup page on https://pro.custodib.us/, and then re-run this script; see https://docs.procustodibus.com/agents/install/ for more info
WARNING libsodium not found
OK will install libsodium
python 3.8.5 found at /usr/bin/python3
WARNING python missing these packages: ensurepip
OK will install missing packages
WARNING python virtualenv not found at /opt/venvs/procustodibus-agent
OK will create virtualenv
WARNING agent package not installed
OK will install agent
WARNING systemd daemon not found at /etc/systemd/system/procustodibus-agent.service
OK will install daemon
WARNING daemon not running
OK will start daemon
dryrun complete

Force

Running the installer with the --force flag will automatically select yes for all prompts. This is how you’d want to run the installer as part of an automated deploy script.

$ sudo ./install.sh --install --force

Requirements

The agent requires Python 3.6 or newer, and libsodium. The installer can install both requirements for you on most Linux platforms via package manager.

Python

If the installer can’t install Python for you, follow these instructions to install Python on the host manually:

Make sure you install at least Python 3.6 or newer. Once you install Python, use the INSTALL_PYTHON environment variable to point the agent installer to your Python executable:

$ sudo INSTALL_PYTHON=/usr/bin/python3.8 ./install.sh --install

Libsodium

If the installer can’t install libsodium for you, follow the Libsodium Installation instructions from the libsodium documentation to build and install libsodium on the host manually. Also see the Installing Libsodium on Amazon Linux 2023 article for a complete, step-by-step guide to this on Amazon Linux 2023.

If you installed libsodium into /usr/local/lib on Linux, make sure /usr/local/lib is in your shared library path. Run ldconfig -p | grep libsodium to check. If not, add /usr/local/lib to your /etc/ld.so.conf file, and then run the ldconfig command (as root).

Troubleshooting

Any WARNING output the installer generates are issues the installer will automatically fix for you (if you answer yes to its prompts). But if you see any ERROR output, here’s what to do:

Must run as root

If the installer outputs ERROR must run as root, make sure you are running the installer as the root user. Try running the installer with the sudo command, like sudo ./install.sh --install.

Agent configuration not found

If the installer outputs ERROR agent configuration not found, make sure you’ve downloaded the procustodibus.conf file and moved it to /etc/wireguard/procustodibus.conf on the host. See the Set Up Host instructions for details.

Agent credentials not found

If the installer outputs ERROR agent credentials not found, make sure you’ve downloaded the procustodibus-setup.conf file and moved it to /etc/wireguard/procustodibus-setup.conf on the host. See the Set Up Host instructions for details.

Unable to install libsodium

If the installer outputs ERROR unable to install libsodium, follow the Libsodium installation instructions to install libsodium manually, and then re-run the installer.

Unable to install python

If the installer outputs ERROR unable to install python, follow the Python installation instructions to install Python manually, and then re-run the installer. When you re-run the installer, make sure you set the INSTALL_PYTHON environment variable to the path to the Python executable you just installed (eg sudo INSTALL_PYTHON=/usr/bin/python3.8 ./install.sh --install).

Python 3.6 required

If the installer outputs ERROR python 3.x.x found at /usr/bin/python3 but at least 3.6 required, follow the Python installation instructions to install Python manually, and then re-run the installer. When you re-run the installer, make sure you set the INSTALL_PYTHON environment variable to the path to the Python executable you just installed (eg sudo INSTALL_PYTHON=/usr/bin/python3.8 ./install.sh --install).

Unable to install missing python packages

If the installer outputs ERROR unable to install missing python packages, follow the Python installation instructions to install Python manually, and then re-run the installer. When you re-run the installer, make sure you set the INSTALL_PYTHON environment variable to the path to the Python executable you just installed (eg sudo INSTALL_PYTHON=/usr/bin/python3.8 ./install.sh --install).

Failed building wheel for pynacl

If the installer outputs ERROR: Failed building wheel for pynacl, or displays similar errors like:

  • pip subprocess to install build dependencies did not run successfully

  • Installing build dependencies …​ error

  • Encountered error while trying to install package cffi

  • command 'gcc' failed: No such file or directory

  • The 'make' utility is missing from PATH

  • ffi.h: No such file or directory

Install your OS’s gcc, make, libffi-dev (or libffi-devel), and python3-dev (or python3-devel) packages, and then re-run the installer.

The following commands will make sure you have the necessary OS packages to build the PyNaCl wheel on most Linux distributions:

  • On Debian-based distros, run sudo apt-get install gcc libffi-dev make python3-dev.

  • On Fedora-based distros, run sudo dnf install findutils gcc libffi-devel make python3-devel.

  • On Arch-based distros, run sudo pacman -Sy gcc make libffi.

  • On Alpine-based distros, run apk add gcc libffi-dev make musl-dev python3-dev.