> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/TecharoHq/Anubis/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy Configuration

Anubis uses YAML-based policy files to define bot protection rules, storage backends, logging, and other security settings. This page covers the structure and loading of policy files.

## Policy File Structure

A complete policy file includes:

```yaml theme={null}
# Bot detection and response rules
bots:
  - name: example-rule
    user_agent_regex: ".*bot.*"
    action: DENY

# Storage backend configuration
store:
  backend: bbolt
  parameters:
    path: /data/anubis.bdb

# Weight-based thresholds
thresholds:
  - name: moderate-suspicion
    expression:
      all:
        - weight >= 10
        - weight < 20
    action: CHALLENGE
    challenge:
      algorithm: fast
      difficulty: 2

# Logging configuration
logging:
  sink: stdio
  level: INFO

# HTTP status codes for responses
status_codes:
  CHALLENGE: 200
  DENY: 200

# DNS settings
dnsbl: false
dns_ttl:
  forward: 300
  reverse: 300

# Optional: Open Graph tag passthrough
openGraph:
  enabled: false

# Optional: Impressum/imprint information
impressum:
  name: "Your Organization"
  email: "contact@example.com"
```

## Loading Policy Files

Anubis loads policy files using the `--policy-fname` flag or `POLICY_FNAME` environment variable:

```bash theme={null}
anubis --policy-fname /etc/anubis/policy.yaml
```

If no policy file is specified, Anubis uses a built-in default policy from `data/botPolicies.yaml`.

### Import Statements

Policy files support importing other YAML files:

```yaml theme={null}
bots:
  - import: "/path/to/shared-rules.yaml"
  - import: "(data)/crawlers.yaml"  # Built-in policies
```

The `(data)/` prefix references embedded policy files shipped with Anubis.

## Configuration Validation

Anubis validates all configuration at startup using the `Valid()` method pattern. Common validation errors:

### Required Fields

* At least one bot rule must be defined (`ErrNoBotRulesDefined`)
* Each bot rule must have a `name` field (`ErrBotMustHaveName`)
* Bots must match on at least one field: `user_agent_regex`, `path_regex`, `headers_regex`, `remote_addresses`, or `expression` (`ErrBotMustHaveUserAgentOrPath`)

### Rule Actions

Valid actions are:

* `ALLOW` - Bypass all checks and forward to backend
* `DENY` - Block the request with a fake success page
* `CHALLENGE` - Present a proof-of-work challenge
* `WEIGH` - Adjust request suspicion weight
* `DEBUG_BENCHMARK` - Development only

### Regular Expression Validation

Regular expressions are compiled at config load time. Common issues:

* Regex ending with newline (`ErrRegexEndsWithNewline`) - use `>-` instead of `>` in YAML:

```yaml theme={null}
# Wrong - includes trailing newline
user_agent_regex: >
  Mozilla.*

# Correct - strips trailing newline  
user_agent_regex: >-
  Mozilla.*
```

### CIDR Validation

IP address ranges in `remote_addresses` must be valid CIDR notation:

```yaml theme={null}
# Valid
remote_addresses:
  - 192.168.0.0/16
  - 10.0.0.0/8
  - 2001:db8::/32

# Invalid - missing /mask
remote_addresses:
  - 192.168.0.1  # Error: invalid CIDR
```

## Configuration Defaults

If not specified in the policy file, Anubis uses these defaults:

```yaml theme={null}
status_codes:
  CHALLENGE: 200
  DENY: 200

dns_ttl:
  forward: 300
  reverse: 300

store:
  backend: memory
  parameters: {}

logging:
  sink: stdio
  level: INFO
```

## Environment-Specific Configuration

Policy files can reference environment variables through standard Go flag environment variable support:

```bash theme={null}
# Set via environment
export POLICY_FNAME=/etc/anubis/prod-policy.yaml
export DIFFICULTY=4

# Or via flags
anubis --policy-fname /etc/anubis/prod-policy.yaml --difficulty 4
```

## Configuration Reloading

Anubis does not currently support hot-reloading of policy files. Configuration changes require a service restart:

```bash theme={null}
sudo systemctl restart anubis
```

## Next Steps

* [Bot Rules](/admin/bot-rules) - Define detection rules
* [Challenge Configuration](/admin/challenge-configuration) - Configure proof-of-work settings
* [Storage Backends](/admin/storage-backends) - Choose a storage backend
* [Security](/admin/security) - Key generation and JWT signing