Native Installation

Install Anubis using native packages or binaries

Anubis can be installed directly on your system using native packages for Debian, Red Hat, or as a standalone binary.

Downloading Anubis

Download the appropriate package for your system from the latest GitHub release.

Installation Methods

Debian/Ubuntu (apt)

1. Install the package

   sudo apt install ./anubis-$VERSION-$ARCH.deb
   

   This installs:

   • Binary at /usr/bin/anubis
   • Systemd service template at /etc/systemd/system/anubis@.service
   • Default configuration at /etc/anubis/default.env
   • Example policy file at /usr/share/doc/anubis/botPolicies.yaml
2. Create instance configuration

   Copy the default configuration for your service (e.g., for Gitea):

   sudo cp /etc/anubis/default.env /etc/anubis/gitea.env
   
3. Copy the policy file

   sudo cp /usr/share/doc/anubis/botPolicies.yaml /etc/anubis/gitea.botPolicies.yaml
   
4. Configure the instance

   Edit /etc/anubis/gitea.env with your settings:

   BIND=[::1]:8239
   BIND_NETWORK=tcp
   DIFFICULTY=4
   METRICS_BIND=[::1]:8240
   METRICS_BIND_NETWORK=tcp
   POLICY_FNAME=/etc/anubis/gitea.botPolicies.yaml
   TARGET=http://localhost:3000
   
5. Enable and start the service

   sudo systemctl enable --now [e-mail]
   
6. Verify it's running

   curl http://[::1]:8240/metrics
   

Red Hat/Fedora/CentOS (rpm)

1. Install the package

   Using dnf:

   sudo dnf -y install ./anubis-$VERSION.$ARCH.rpm
   

   Or using yum:

   sudo yum -y install ./anubis-$VERSION.$ARCH.rpm
   

   Or using rpm directly:

   sudo rpm -ivh ./anubis-$VERSION.$ARCH.rpm
   

   This installs:

   • Binary at /usr/bin/anubis
   • Systemd service template at /etc/systemd/system/anubis@.service
   • Default configuration at /etc/anubis/default.env
   • Example policy file at /usr/share/doc/anubis/botPolicies.yaml
2. Create instance configuration

   Copy the default configuration for your service (e.g., for Gitea):

   sudo cp /etc/anubis/default.env /etc/anubis/gitea.env
   
3. Copy the policy file

   sudo cp /usr/share/doc/anubis/botPolicies.yaml /etc/anubis/gitea.botPolicies.yaml
   
4. Configure the instance

   Edit /etc/anubis/gitea.env with your settings:

   BIND=[::1]:8239
   BIND_NETWORK=tcp
   DIFFICULTY=4
   METRICS_BIND=[::1]:8240
   METRICS_BIND_NETWORK=tcp
   POLICY_FNAME=/etc/anubis/gitea.botPolicies.yaml
   TARGET=http://localhost:3000
   
5. Enable and start the service

   sudo systemctl enable --now [e-mail]
   
6. Verify it's running

   curl http://[::1]:8240/metrics
   

Tarball (Generic Linux)

1. Extract the tarball

   tar zxf ./anubis-$VERSION-$OS-$ARCH.tar.gz
   cd anubis-$VERSION-$OS-$ARCH
   
2. Install the binary

   sudo install -D ./bin/anubis /usr/local/bin/anubis
   
3. Update the systemd unit path

   perl -pi -e 's$/usr/bin/anubis$/usr/local/bin/anubis$g' ./run/anubis@.service
   
4. Install systemd service

   sudo install -D ./run/anubis@.service /etc/systemd/system/anubis@.service
   
5. Install default configuration

   sudo install -D ./run/default.env /etc/anubis/default.env
   
6. Create instance configuration

   sudo cp /etc/anubis/default.env /etc/anubis/gitea.env
   
7. Copy the policy file

   sudo cp ./doc/botPolicies.yaml /etc/anubis/gitea.botPolicies.yaml
   
8. Configure the instance

   Edit /etc/anubis/gitea.env with your settings:

   BIND=[::1]:8239
   BIND_NETWORK=tcp
   DIFFICULTY=4
   METRICS_BIND=[::1]:8240
   METRICS_BIND_NETWORK=tcp
   POLICY_FNAME=/etc/anubis/gitea.botPolicies.yaml
   TARGET=http://localhost:3000
   
9. Reload systemd and start the service

   sudo systemctl daemon-reload
   sudo systemctl enable --now [e-mail]
   
10. Verify it's running

    curl http://[::1]:8240/metrics
    

Distribution Package Manager

Some Linux distributions include Anubis in their official repositories. Check Repology for availability.

The package name varies by distribution:

• anubis (most distributions)
• www-apps/anubis (Gentoo)
• www/anubis (BSD ports)

1. Install via package manager

   Example for distributions with anubis in repos:

   # Example - check your distribution's documentation
   sudo apt install anubis
   # or
   sudo dnf install anubis
   
2. Follow systemd setup

   If your distribution uses systemd, follow the configuration steps from the Debian or Red Hat tabs above.

Systemd Service Configuration

Service Template

Anubis uses a systemd service template (anubis@.service) that allows running multiple instances. The instance name (e.g., gitea) determines which configuration file to load:

• Service: [e-mail]
• Config file: /etc/anubis/gitea.env

Managing Services

Start Service

sudo systemctl start [e-mail]

Configuration Files

Environment File Format

Configuration files in /etc/anubis/ use environment variable syntax:

# /etc/anubis/gitea.env
BIND=[::1]:8239
BIND_NETWORK=tcp
DIFFICULTY=4
METRICS_BIND=[::1]:8240
POLICY_FNAME=/etc/anubis/gitea.botPolicies.yaml
TARGET=http://localhost:3000
COOKIE_DOMAIN=example.com
COOKIE_EXPIRATION_TIME=168h
SLOG_LEVEL=INFO

See the Configuration reference for all available options.

Policy Files

Bot policy files use YAML format:

# /etc/anubis/gitea.botPolicies.yaml
bots:
  - name: "OpenAI GPTBot"
    rules:
      userAgentContains: "GPTBot"
    action: deny

  - name: "Common crawlers"
    rules:
      userAgentContains: "bot"
    action: challenge

For more details, see the Bot Policies documentation.

Running Multiple Instances

Protect multiple services by creating separate configuration files:

# Protect Gitea on port 8239
sudo cp /etc/anubis/default.env /etc/anubis/gitea.env
sudo systemctl enable --now [e-mail]

# Protect another service on port 8241
sudo cp /etc/anubis/default.env /etc/anubis/myapp.env
sudo systemctl enable --now [e-mail]

Each instance runs independently with its own configuration.

Health Checks

HTTP Health Endpoint

Check if Anubis is running:

curl http://localhost:9090/healthz

Returns OK when Anubis is serving traffic.

Built-in Health Check

Use the --healthcheck flag:

anubis --healthcheck

Exits with code 0 if healthy, non-zero otherwise.

Signing Keys

When using persistent storage backends or running multiple Anubis instances behind the same load balancer, you must configure a signing key.

Generate an ED25519 private key:

openssl rand -hex 32 | sudo tee /etc/anubis/signing.key
sudo chmod 600 /etc/anubis/signing.key
sudo chown root:root /etc/anubis/signing.key

Add to your configuration file:

ED25519_PRIVATE_KEY_HEX_FILE=/etc/anubis/signing.key

All instances protecting the same domain must use the same signing key.

Reverse Proxy Integration

After installing Anubis, configure your reverse proxy to route traffic through it:

Nginx

Configure Nginx reverse proxy

Apache

Configure Apache reverse proxy

Caddy

Configure Caddy reverse proxy

HAProxy

Configure HAProxy

Traefik

Configure Traefik

Kubernetes

Deploy on Kubernetes

Troubleshooting

Service won’t start

Check the logs:

sudo journalctl -u [e-mail] -n 50

Common issues:

• Port already in use (check BIND and METRICS_BIND)
• Invalid policy file path or syntax
• Missing signing key with persistent storage

Permission denied errors

Ensure configuration files are readable:

sudo chmod 644 /etc/anubis/gitea.env
sudo chmod 644 /etc/anubis/gitea.botPolicies.yaml

Can’t reach target service

Verify the TARGET URL is correct and the service is running:

curl http://localhost:3000  # Replace with your TARGET

Next Steps

Configuration

Explore all configuration options

Bot Policies

Configure bot detection rules