Installation Guide

Install the Defensia security agent on your Linux server in under 30 seconds. One command, fully automated.

Requirements

  • Linux kernel 3.10+— CentOS 7 and later
  • Init system— systemd, Upstart or SysVinit — detected automatically
  • Package manager— apt, yum or dnf — the installer needs one to fetch missing dependencies
  • Root access— sudo or root shell
  • curl— Auto-installed if missing
  • iptables— Auto-installed if missing
  • Internet access— HTTPS outbound to your Defensia panel

See the full list of supported distributions and architectures on the Supported Systems page.

Get your install token in seconds — just enter your email:

No password needed. We will send you a link to set it up.

Free plan includes 1 server. No credit card required.

1

Sign in to the dashboard

Go to your Defensia dashboard and sign in with your account. If you do not have an account yet, create one for free.

Sign in to Dashboard
2

Generate an install token

From your dashboard, click "Add Server" to generate a one-time install token. This token is used to authenticate the agent during installation.

Install tokens are single-use and expire one hour after you generate them. You can generate a new one at any time from the dashboard — generate it when you are ready to run the command, not in advance.

Copy the whole token. It is exactly 64 characters, and the panel accepts nothing else. A token clipped short or padded with a newline by a terminal paste is the single most common install failure. Agent 1.4.78 and newer checks the length before contacting the panel and tells you so directly.

3

Run the install command

SSH into your server and run the following command as root (or with sudo):

curl -fsSL https://defensia.cloud/install.sh | sudo bash -s -- --token <YOUR_TOKEN>

Replace <YOUR_TOKEN> with the token generated in Step 2.

Registration is rate limited. Each install token allows 15 attempts a minute and 40 an hour, and each source address 60 a minute and 300 an hour — comfortable for a normal install, including a retry or two, and for several servers behind one NAT. If you do hit the limit, the response says so explicitly: wait for the window and run the same command again. Regenerating the token does not help, because the token is not what was exhausted. See Troubleshooting.

What the installer does

  • Detects your OS distribution, version, architecture (amd64/arm64) and init system
  • Installs curl, iptables and ca-certificates if missing, via apt, yum or dnf
  • Installs ipset if available — raises firewall capacity from 500 to 65,536 bans
  • Downloads the correct pre-compiled agent binary
  • Installs the binary to /usr/local/bin/defensia-agent
  • Creates the configuration directory at /etc/defensia/
  • Registers the agent with the Defensia server using your token
  • Writes /etc/defensia/config.json with the returned auth token
  • Creates and enables a service for your init system (systemd, Upstart or SysVinit)
  • Starts the agent and sends the first heartbeat

Verifying the installation

After installation, verify the agent is running with:

sudo systemctl status defensia-agent

You should see active (running) in the output. The agent will also appear as "online" in your dashboard within a few seconds.

To view real-time agent logs:

sudo journalctl -u defensia-agent -f

Automatic Updates

The agent supports automatic updates managed from the admin panel. When a platform administrator publishes a new agent version, connected agents will automatically download and apply the update.

How it works

  • On each heartbeat, the server returns the latest agent version (if configured)
  • The agent compares its current version with the latest version using semver
  • If a newer version is available, the agent downloads the binary for its architecture (amd64/arm64)
  • The downloaded binary is verified against a SHA256 checksum
  • The binary at /usr/local/bin/defensia-agent is replaced with the new version
  • The agent service is restarted via systemctl to apply the update

Updates are verified with SHA256 checksums before being applied. The agent will restart automatically after a successful update. No manual intervention is required.

Docker Installation

Run the Defensia agent as a Docker container. This is ideal for servers where you prefer containerized workloads or want to avoid installing binaries directly on the host.

Docker Run

docker run -d \
  --name defensia-agent \
  --restart unless-stopped \
  --network host \
  --pid host \
  -v /var/log:/var/log:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /etc/defensia:/etc/defensia \
  -e DEFENSIA_TOKEN=<YOUR_TOKEN> \
  -e DEFENSIA_SERVER_URL=https://defensia.cloud \
  ghcr.io/defensia/agent:latest

The docker.sock mount enables Docker container detection. The /var/log mount gives access to system and web server logs for SSH and WAF monitoring.

Docker Compose

Add the Defensia agent to an existing Docker Compose stack. Drop this snippet into your docker-compose.yml file:

services:
  defensia-agent:
    image: ghcr.io/defensia/agent:latest
    container_name: defensia-agent
    restart: unless-stopped
    network_mode: host
    pid: host
    volumes:
      - /var/log:/var/log:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /etc/defensia:/etc/defensia
    environment:
      DEFENSIA_TOKEN: "<YOUR_TOKEN>"
      DEFENSIA_SERVER_URL: "https://defensia.cloud"

Then run docker compose up -d defensia-agent to start the agent.

Docker Swarm

Deploy the agent as a global Swarm service so every node in your cluster is automatically protected. Swarm uses an Organization API Key instead of an install token: one key registers every node, while an install token is single-use and would only register the first node.

1. Get an Organization API Key

In the dashboard, click Add server → Kubernetes / Swarm, enter a name for the cluster and click Generate Key. Copy the key right away — it is only shown once.

2. Store it as a Docker secret

echo "<YOUR_ORG_API_KEY>" | docker secret create defensia_api_key -

3. Create the global service

docker service create \
  --name defensia-agent \
  --mode global \
  --network host \
  --cap-add NET_ADMIN \
  --cap-add NET_RAW \
  --secret defensia_api_key \
  --mount type=bind,src=/var/log,dst=/var/log,readonly \
  --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock,readonly \
  --mount type=volume,src=defensia-config,dst=/etc/defensia \
  -e DEFENSIA_API_KEY_FILE=/run/secrets/defensia_api_key \
  -e NODE_NAME="{{.Node.Hostname}}" \
  -e DEFENSIA_SERVER_URL=https://defensia.cloud \
  ghcr.io/defensia/agent:latest

The --mode global flag ensures one agent replica runs on every Swarm node. New nodes added to the cluster will automatically receive an agent instance and register with the same key. NODE_NAME makes each node appear in the dashboard under its Swarm hostname instead of a container ID.

Or as a stack file

# docker-compose.swarm.yml
services:
  agent:
    image: ghcr.io/defensia/agent:latest
    deploy:
      mode: global
    networks: [hostnet]
    cap_add: [NET_ADMIN, NET_RAW]
    environment:
      DEFENSIA_API_KEY_FILE: /run/secrets/defensia_api_key
      NODE_NAME: "{{.Node.Hostname}}"
      DEFENSIA_SERVER_URL: "https://defensia.cloud"
    volumes:
      - /var/log:/var/log:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - defensia-config:/etc/defensia
    secrets: [defensia_api_key]

networks:
  hostnet:
    external: true
    name: host

secrets:
  defensia_api_key:
    external: true

volumes:
  defensia-config:

Then run docker stack deploy -c docker-compose.swarm.yml defensia.

The defensia-config volume keeps each node's agent credentials in /etc/defensia, so a restarted or rescheduled task reconnects as the same server instead of registering again. Each node uses one server slot on your plan. Do not use DEFENSIA_TOKEN in a Swarm service — install tokens are single-use. If you prefer per-node tokens, run the single-container docker run command above on each node with its own token.

Kubernetes (Helm)

Deploy the Defensia agent as a DaemonSet across your Kubernetes cluster using the official Helm chart. Every node gets an agent that monitors ingress traffic, API audit logs, and pod events.

Quick install

helm install defensia-agent \
  oci://ghcr.io/defensia/charts/defensia-agent \
  --set apiKey="<YOUR_ORG_API_KEY>" \
  --set serverUrl="https://defensia.cloud" \
  --namespace defensia-system \
  --create-namespace

What gets deployed

  • A DaemonSet that runs one agent pod on every node (including control-plane nodes)
  • A ServiceAccount with ClusterRole for Kubernetes API access
  • RBAC bindings for reading pods, nodes, events, and ingress resources
  • A Secret holding your organization API key, plus the server URL
  • Chart defaults: 50m CPU / 64Mi RAM requested, 500m CPU / 256Mi RAM limit (override in values.yaml)

Custom values

# values.yaml
apiKey: "your-org-api-key"         # Dashboard → Add server → Kubernetes / Swarm
serverUrl: "https://defensia.cloud"
clusterName: "production"          # auto-detected if omitted

resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 50m
    memory: 64Mi

tolerations:
  - operator: Exists          # run on all nodes

Kubernetes deployments use an Organization API Key instead of per-server install tokens. Generate one from the dashboard under Add server → Kubernetes / Swarm → Generate Key. All images are signed with Cosign and the Helm chart includes GPG provenance.

Uninstalling

To completely remove the Defensia agent from your server:

sudo systemctl stop defensia-agent
sudo systemctl disable defensia-agent
sudo rm /usr/local/bin/defensia-agent
sudo rm /etc/systemd/system/defensia-agent.service
sudo rm -rf /etc/defensia
sudo systemctl daemon-reload

Then remove the server from your dashboard. Any bans applied by this agent will remain active unless you manually remove them.

Environment Variables

Credentials live in /etc/defensia/config.json, written by the installer — it holds the server URL, the agent token and the agent ID, and you should not need to edit it. Everything below is an environment variable, set in the service unit at /etc/systemd/system/defensia-agent.service as Environment="NAME=value" lines. Run systemctl daemon-reload && systemctl restart defensia-agent after changing one.

Detection tuning — ban threshold, time window, ban duration, monitor mode, WAF types, blocked countries — is not configured on the server. It is set per server in the dashboard and delivered to the agent over the sync endpoint, so a change takes effect without touching the host. The variables below only cover things the agent cannot discover for itself.

VariableDescriptionDefault
DEFENSIA_CONFIGPath to the credentials file written at install time/etc/defensia/config.json
AUTH_LOG_PATHSSH auth log. Set by the installer; falls back to journald when no file exists(auto-detected)
WEB_LOG_PATHWeb server access logs for the WAF. Comma-separated; overrides all auto-detection(auto-detected)
MAIL_LOG_PATHPostfix / Dovecot log for mail brute-force detection(auto-detected)
FTP_LOG_PATHPure-FTPD / ProFTPD log for FTP brute-force detection(auto-detected)
DB_LOG_PATHMySQL / MariaDB log for auth-failure detection(auto-detected)
MODSEC_AUDIT_LOGModSecurity audit log, when not at the distro default path(auto-detected)
GEOIP_DB_PATHMaxMind GeoLite2 country database used for geoblocking(bundled)
AGENT_IPOverride the detected outbound IP. Must be a valid IP — anything else is ignored with a warning(auto-detected)
DEFENSIA_DATA_DIRDirectory for file-integrity baselines/etc/defensia