Storage Configuration

Overview

Anubis uses pluggable storage backends to persist client state, challenge tokens, and bot detection metadata. The storage configuration determines which backend to use and its parameters.

Store

Storage backend configuration struct.

Type Definition

type Store struct {
    Backend    string          `json:"backend"`
    Parameters json.RawMessage `json:"parameters"`
}

Fields

Backend

string

required

Storage backend type. Must be a registered store backend.Built-in backends:

"memory" - In-memory storage (default, not persistent)
"bbolt" - BoltDB embedded database
"valkey" - Valkey/Redis compatible server
"s3api" - S3-compatible object storage

Parameters

json.RawMessage

Backend-specific configuration as raw JSON. The structure depends on the selected backend.

Validation Rules

Backend must be non-empty
Backend must be a registered store implementation
Parameters must be valid according to the backend’s validation rules

Errors

var (
    ErrNoStoreBackend      = errors.New("config.Store: no backend defined")
    ErrUnknownStoreBackend = errors.New("config.Store: unknown backend")
)

Backend-Specific Parameters

Memory Backend

The memory backend requires no parameters. State is stored in-process and lost on restart.

store:
  backend: memory

BoltDB Backend

Embedded database stored in a local file.

store:
  backend: bbolt
  parameters:
    path: "./var/anubis.db"
    mode: 0600

Parameters:

path (string, required): Filesystem path to the database file
mode (int, optional): File permissions in octal (default: 0600)

Valkey/Redis Backend

Connect to a Valkey or Redis server.

store:
  backend: valkey
  parameters:
    address: "localhost:6379"
    password: "secret"
    db: 0
    poolSize: 10

Parameters:

address (string, required): Server address (host:port)
password (string, optional): Authentication password
db (int, optional): Database number (default: 0)
poolSize (int, optional): Connection pool size
tls (bool, optional): Enable TLS

S3 Backend

Use S3-compatible object storage (AWS S3, MinIO, etc.).

store:
  backend: s3api
  parameters:
    bucket: "anubis-state"
    region: "us-east-1"
    endpoint: "https://s3.amazonaws.com"
    accessKeyId: "AKIAIOSFODNN7EXAMPLE"
    secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

Parameters:

bucket (string, required): S3 bucket name
region (string, required): AWS region
endpoint (string, optional): Custom S3 endpoint (for S3-compatible services)
accessKeyId (string, required): AWS access key ID
secretAccessKey (string, required): AWS secret access key
sessionToken (string, optional): AWS session token

Default Configuration

When no store is specified, Anubis defaults to in-memory storage:

Store: &Store{
    Backend: "memory",
}

StatusCodes

HTTP status codes returned for different actions.

Type Definition

type StatusCodes struct {
    Challenge int `json:"CHALLENGE"`
    Deny      int `json:"DENY"`
}

Fields

Challenge

int

default:"200"

HTTP status code to return when presenting a challenge. Valid range: 100-599.Common values:

200 - OK (default, challenge rendered in response body)
403 - Forbidden
429 - Too Many Requests

Deny

int

default:"200"

HTTP status code to return when denying a request. Valid range: 100-599.Common values:

200 - OK (default, denial message in response body)
403 - Forbidden
429 - Too Many Requests
503 - Service Unavailable

Validation Rules

Both Challenge and Deny must be set
Both must be in range 100-599

Errors

var (
    ErrStatusCodeNotValid = errors.New("config.StatusCode: status code not valid, must be between 100 and 599")
)

Example

status_codes:
  CHALLENGE: 429
  DENY: 403

DnsTTL

DNS cache TTL settings for reverse DNS lookups.

Type Definition

type DnsTTL struct {
    Forward int `json:"forward"`
    Reverse int `json:"reverse"`
}

Fields

Forward

int

default:"300"

TTL in seconds for forward DNS lookups (hostname to IP). Must be >= 0.

Reverse

int

default:"300"

TTL in seconds for reverse DNS lookups (IP to hostname). Must be >= 0.

Example

dns_ttl:
  forward: 600
  reverse: 600

Logging

Logging configuration for Anubis.

Type Definition

type Logging struct {
    Sink       string             `json:"sink"`
    Level      *slog.Level        `json:"level"`
    Parameters *LoggingFileConfig `json:"parameters"`
}

Fields

Sink

string

default:"stdio"

Logging output sink. Valid values: "stdio", "file".

Level

*slog.Level

Log level. If set, overrides the level from command-line flags.Valid levels:

slog.LevelDebug (-4)
slog.LevelInfo (0)
slog.LevelWarn (4)
slog.LevelError (8)

Parameters

*LoggingFileConfig

File logging configuration. Required when Sink is "file".

Validation Rules

If Sink is "file", Parameters must be set
Parameters must pass its own validation

Errors

var (
    ErrMissingLoggingFileConfig = errors.New("config.Logging: missing value parameters in logging block")
    ErrInvalidLoggingSink       = errors.New("config.Logging: invalid sink")
)

LoggingFileConfig

File-based logging configuration with log rotation.

Type Definition

type LoggingFileConfig struct {
    Filename     string `json:"file"`
    MaxBackups   int    `json:"maxBackups"`
    MaxBytes     int64  `json:"maxBytes"`
    MaxAge       int    `json:"maxAge"`
    Compress     bool   `json:"compress"`
    UseLocalTime bool   `json:"useLocalTime"`
}

Fields

Filename

string

required

Path to the log file.

MaxBackups

int

default:"3"

Maximum number of old log files to retain. Must be >= 0.

MaxBytes

int64

default:"104857600"

Maximum size in bytes before rotating the log file (default: 100 MiB).

MaxAge

int

default:"7"

Maximum number of days to retain old log files. Must be >= 0.

Compress

bool

default:"true"

Compress rotated log files using gzip.

UseLocalTime

bool

default:"false"

Use local time for log file timestamps instead of UTC.

Validation Rules

Filename must be set
MaxBackups must be >= 0
MaxAge must be >= 0

Errors

var (
    ErrInvalidLoggingFileConfig = errors.New("config.LoggingFileConfig: invalid parameters")
    ErrOutOfRange               = errors.New("config: error out of range")
)

Example

logging:
  sink: file
  parameters:
    file: "./var/anubis.log"
    maxBackups: 5
    maxBytes: 209715200  # 200 MiB
    maxAge: 14
    compress: true
    useLocalTime: false

OpenGraph

OpenGraph metadata configuration for social media previews.

Type Definition

type OpenGraph struct {
    Override     map[string]string `json:"override,omitempty" yaml:"override,omitempty"`
    TimeToLive   time.Duration     `json:"ttl" yaml:"ttl"`
    Enabled      bool              `json:"enabled" yaml:"enabled"`
    ConsiderHost bool              `json:"considerHost" yaml:"enabled"`
}

Fields

Enabled

bool

default:"false"

Enable OpenGraph tag caching and customization.

ConsiderHost

bool

default:"false"

Include the request hostname when caching OpenGraph tags.

TimeToLive

time.Duration

Duration to cache OpenGraph tags (e.g., "5m", "1h", "24h").

Override

map[string]string

Custom OpenGraph tags to inject. Keys are tag names (e.g., "og:title").Required tags when using overrides:

"og:title" - Page title

Example

openGraph:
  enabled: true
  considerHost: true
  ttl: "1h"
  override:
    og:title: "My Protected Site"
    og:description: "Protected by Anubis"
    og:image: "https://example.com/og-image.png"

Complete Configuration Example

store:
  backend: valkey
  parameters:
    address: "localhost:6379"
    db: 0
    poolSize: 20

status_codes:
  CHALLENGE: 429
  DENY: 403

dns_ttl:
  forward: 300
  reverse: 300

logging:
  sink: file
  parameters:
    file: "./var/anubis.log"
    maxBackups: 3
    maxBytes: 104857600
    maxAge: 7
    compress: true
    useLocalTime: false

openGraph:
  enabled: true
  ttl: "30m"
  override:
    og:title: "Protected Site"

bots:
  # Bot rules here...

Core Library

Configuration

​Overview

​Store

​Type Definition

​Fields

​Validation Rules

​Errors

​Backend-Specific Parameters

​Memory Backend

​BoltDB Backend

​Valkey/Redis Backend

​S3 Backend

​Default Configuration

​StatusCodes

​Type Definition

​Fields

​Validation Rules

​Errors

​Example

​DnsTTL

​Type Definition

​Fields

​Example

​Logging

​Type Definition

​Fields

​Validation Rules

​Errors

​LoggingFileConfig

​Type Definition

​Fields

​Validation Rules

​Errors

​Example

​OpenGraph

​Type Definition

​Fields

​Example

​Complete Configuration Example

Build docs developers (and LLMs) love

Overview

Store

Type Definition

Fields

Validation Rules

Errors

Backend-Specific Parameters

Memory Backend

BoltDB Backend

Valkey/Redis Backend

S3 Backend

Default Configuration

StatusCodes

Type Definition

Fields

Validation Rules

Errors

Example

DnsTTL

Type Definition

Fields

Example

Logging

Type Definition

Fields

Validation Rules

Errors

LoggingFileConfig

Type Definition

Fields

Validation Rules

Errors

Example

OpenGraph

Type Definition

Fields

Example

Complete Configuration Example