Skip to content

Installation

Symptoms covered on this page

  • The installer prints a Fatal: message and stops.
  • The installer completes, but the deployment stays at Not Set Up.
  • Docker is installed but the foothold cannot use it.
  • The OVA appliance will not finish its guided setup.

The installer runs in two stages. A small native binary — the dropper — checks the host, then downloads and runs a shell bootstrapper that installs the tooling and registers the foothold as a service. Knowing which stage failed tells you which section below applies: the dropper's messages are prefixed Fatal: and appear before anything is installed, and the bootstrapper's messages appear after it has started installing prerequisites.

Installer messages and what they mean

No shell detected. This utility cannot run on a system without a shell.

The dropper needs a shell to run the bootstrapper. It prefers Bash and falls back to POSIX sh. A host with neither — a minimal container image, or a hardened appliance — cannot be used as a foothold.

Use a supported host, or deploy the foothold as a Docker container instead, which does not use the installer at all.

Failed to establish whether an internet connection is present. Is the ping utility missing from your system?

The dropper pings 127.0.0.1 to confirm that ping works before it uses it for anything else. This message means ping is missing, not that the network is down.

# Debian and Ubuntu
sudo apt-get install -y iputils-ping

If installing ping is not an option, skip the dropper's connectivity checks:

./fdrop-linux-x64 --no-connectivity-check

This utility requires PowerShell, wget or curl for networking.

The message is the dropper's generic one. On a Linux host it downloads the bootstrapper using whichever of wget, curl or python3 it finds first, so install one of those:

# Debian and Ubuntu
sudo apt-get install -y curl

This system is not connected to the internet… or …cannot reach the BreachLock platform

A network problem rather than an installation one. The second message names the hostname the installer could not reach, which is the one to allowlist. See Host Connectivity.

Could not download bootstrapper. Are you connected to the internet, or could your firewall/antivirus software be interfering?

The host reached the platform but the download did not complete. In practice this is almost always one of two things:

  • Endpoint protection blocked the download. Security software frequently quarantines the bootstrapper because it installs penetration-testing tooling. See Endpoint protection.
  • The deployment secret in the command has expired or was truncated. Copy the installation command again from the platform rather than reusing an old one, and paste it whole.

Insufficient space!

The bootstrapper requires at least 10 GB free on the root filesystem before it will start, and the message names how much it found. Note that this floor is lower than the documented host requirement of 60 GB — clearing just enough space to get past the check will let the install proceed and then run out of room later, when the foothold downloads its container image.

df -h /

Unsupported operating system or Unsupported architecture

The bootstrapper could not match the host to a build it can install. The supported host architectures are x64 (x86_64) and arm64 (aarch64), on Ubuntu 20.04 or later.

Check what the host reports:

uname -s -m

If it reports anything other than Linux x86_64 or Linux aarch64, use a supported Linux host or the OVA appliance instead.

Privileges

The installer requires root, and re-launches itself with sudo if it is not already running as root. It needs those rights because it installs system packages, registers a system service, and configures Docker.

If the account running the installer cannot obtain root — sudo is not configured for it, or it is absent from the sudoers file — the install cannot proceed. Run it as a user with sudo rights, or use the OVA appliance, which arrives with everything already installed.

Docker and the container runtime

The foothold runs its heavier tooling inside a container image called sapiens-container, which it downloads and starts itself. Docker must be installed and running on the host before it can do that.

Checking Docker

# Is Docker installed?
docker --version

# Is the daemon running?
systemctl status docker

# Can this account use it, without sudo?
docker run --rm hello-world

permission denied while trying to connect to the Docker daemon socket

The account is not in the docker group. The foothold itself runs as root and is unaffected, so this comes up when you are checking Docker by hand, or when starting a Docker container deployment as your own user.

sudo usermod -aG docker $(whoami)
groups $(whoami)   # confirm "docker" now appears

Group membership is applied at login, so log out and back in (or reboot) before retrying.

Cannot connect to the Docker daemon

The daemon is installed but not running:

sudo systemctl start docker
sudo systemctl enable docker   # so it survives a reboot

Docker is not installed

A root install installs Docker for you. If that step failed, the usual cause is that download.docker.com is not on the outbound allowlist — see Host Connectivity. Install Docker manually following Docker's own instructions and re-run the installer.

masscan failed to install

This one is not a problem. masscan is an optimisation used for network segmentation scans, and the installer treats a failed masscan install as non-fatal — the foothold falls back to nmap. You will see a message saying so, and the installation continues.

Docker container deployments

A Docker container deployment does not use the installer at all. The platform gives you a docker login followed by a docker run, and both halves have to succeed. The generated command uses --network host, so it expects a Linux host running Docker Engine.

The docker login step fails

The host cannot reach the container registry, or the credentials in the command have been rotated. Check that the registry hostname is on your outbound allowlist — see Required outbound whitelisting — and copy a fresh command from the platform rather than reusing a saved one.

The container starts and immediately exits

Check what it said before it stopped:

docker ps -a
docker logs <container-id>

The generated command includes --rm, so a container that exits is removed and disappears from docker ps entirely. If you see nothing at all, run the same command without -d so the output stays on your terminal.

The container runs but the deployment stays at Not Set Up

The SECRET environment variable in the command is what identifies the deployment. If it was truncated when you copied it, the container starts normally and is simply never recognised. Copy the command again from the platform.

Fixing network settings on the OVA appliance

The OVA appliance takes its network configuration during the guided setup — see Configuring the OVA. If you chose Automatic on a network without DHCP, or entered the wrong static details, the appliance boots with no usable address.

Check what it has:

ip addr
ip route

To change it, re-run the setup wizard from the appliance's terminal:

sudo /etc/sapiens/setup

Choose Manual at the network configuration step and supply the IP address, subnet mask, gateway and DNS servers for the segment the appliance sits on. Confirm afterwards:

ip addr show
ping -c 3 <gateway-address>
curl -I https://aev.breachlocklabs.com

The pairing code is rejected

The pairing code rotates every 60 minutes until setup completes, so a code copied at the start of a long OVA import will usually have expired by the time the wizard asks for it. Return to the platform, open the deployment's setup screen, and read the current code.

Also confirm you are entering the code for the right deployment — creating a second deployment while troubleshooting gives you a second, different code, and the wizard will reject one against the other.

The system requirements check fails

The appliance ships configured for 2 CPUs, 5 GB RAM and a 40 GB disk. If you reduced any of these when importing, raise them in your hypervisor's settings and power the VM back on. The appliance is x64 only — it will not run on an Apple Silicon Mac.

Need help? If the installer still will not complete, send us the full installer output along with the details listed in What to send us. Reach out to your BreachLock representative or email support@breachlock.com.