Atheme Configuration

Documentation Index

Fetch the complete documentation index at: https://docs.allthingslinux.org/llms.txt

Use this file to discover all available pages before exploring further.

​

Config template pipeline

1. You set values in .env (copied from .env.example)
2. Running just init or just dev triggers scripts/prepare-config.sh
3. The script sources .env, then .env.dev if it exists (dev overrides)
4. envsubst replaces all ${VAR} references in atheme.conf.template
5. The rendered atheme.conf is written to apps/atheme/config/atheme.conf
6. The config directory is mounted read-only into the container at /usr/local/atheme/etc

Warning: prepare-config.sh unconditionally sources .env.dev if the file exists, even when preparing production configs. Do not leave .env.dev on a production server, or your production Atheme config will contain development overrides.

# Regenerate all configs (including Atheme)
just init

# Or run prepare-config.sh directly
./scripts/prepare-config.sh

​

Environment variables

​

Server identity

​

Network information

​

Uplink connection

Warning: IRC_SERVICES_PASSWORD must match the link password configured in UnrealIRCd. Change this from the default before any public deployment. The same variable is referenced in both atheme.conf.template and unrealircd.conf.template.

​

HTTP daemon

​

Service bot identities

Note: ChanFix variables (ATHEME_CHANFIX_*) are defined in .env.example but only consumed in a commented-out block in the config template. The ChanFix module is disabled by default.

​

Module system

​

Core modules

loadmodule "protocol/unreal4";   /* UnrealIRCd server-to-server protocol */
loadmodule "backend/opensex";    /* Atheme's native flat-file database */
loadmodule "crypto/pbkdf2v2";    /* Password hashing (must load before other crypto) */

• protocol/unreal4 — speaks UnrealIRCd’s S2S protocol. This is the only protocol module you should load for this stack.
• backend/opensex — Atheme’s flat-file database format. The database is stored at data/atheme/data/services.db. This is not SQLite — it is Atheme’s own serialization format.
• crypto/pbkdf2v2 — PBKDF2 v2 password hashing. Must be loaded before any other crypto module to ensure SCRAM-SHA support works correctly.

​

Service modules

​

Disabled modules

• SASL EXTERNAL — certificate-based authentication
• SASL ECDH/ECDSA — elliptic curve challenge mechanisms

​

SASL and password hashing

​

SASL mechanisms

​

PBKDF2v2 configuration

crypto {
    pbkdf2v2_digest = "SCRAM-SHA-256";  /* Enables SCRAM-SHA-256 SASL mechanism */
    pbkdf2v2_rounds = 64000;            /* Iteration count (10000–65536 for SCRAM compat) */
    pbkdf2v2_saltlen = 32;              /* Salt length in bytes */
};

1. Atheme must be built with --with-libidn (the Containerfile includes this)
2. crypto/pbkdf2v2 must be loaded before any other crypto module
3. The digest must be set to a SCRAM-* variant (SCRAM-SHA-256 is recommended)
4. Rounds must be between 10,000 and 65,536 for Cyrus SASL compatibility
5. The saslserv/scram module must be loaded

Note: When you change the pbkdf2v2_digest setting, existing passwords are not automatically re-hashed. Users need to change their password (or re-identify) for the new hash format to take effect.

​

Service bot configuration blocks

​

NickServ

nickserv {
    /* ... identity vars ... */
    aliases {
        "ID" = "IDENTIFY";
        "MYACCESS" = "LISTCHANS";
    };
    spam;                    /* Send spam warnings to users */
    maxnicks = 5;            /* Max nicknames per account */
    expire = 30;             /* Days before unused nicknames expire */
    enforce_expire = 14;     /* Days before enforced nicknames expire */
    enforce_delay = 30;      /* Seconds before nickname enforcement kicks in */
    enforce_prefix = "Guest"; /* Prefix for enforced nickname changes */
    waitreg_time = 30;       /* Seconds a user must wait before registering */
    show_custom_metadata;    /* Show custom metadata in INFO */
};

​

ChanServ

chanserv {
    /* ... identity vars ... */
    maxchans = 5;            /* Max channels per account */
    fantasy;                 /* Enable fantasy commands (e.g., !op, !kick) */
    trigger = "!";           /* Fantasy command prefix */
    expire = 30;             /* Days before unused channels expire */
    maxchanacs = 0;          /* Max access entries per channel (0 = unlimited) */
    maxfounders = 4;         /* Max founders per channel */
    changets;                /* Sync channel TS on registration */
    antiflood_enforce_method = quiet;  /* Flood response: quiet offenders */
    templates {
        vop = "+AV";
        hop = "+AHehitrv";
        aop = "+AOehiortv";
        sop = "+AOaefhiorstv";
        founder = "+AFORaefhioqrstv";
        member = "+Ai";
        op = "+AOiortv";
    };
    deftemplates = "MEMBER=+Ai OP=+AOiortv";
};

​

General settings

general {
    helpchan = "${ATHEME_HELP_CHANNEL}";
    helpurl = "${ATHEME_HELP_URL}";
    join_chans;              /* ChanServ joins registered channels */
    leave_chans;             /* ChanServ leaves when channel empties */
    uflags = { hidemail; };  /* Default user flags */
    cflags = { guard; verbose; };  /* Default channel flags */
    flood_msgs = 7;          /* Messages before flood protection triggers */
    flood_time = 10;         /* Flood detection window (seconds) */
    ratelimit_uses = 5;      /* Command uses before rate limiting */
    ratelimit_period = 60;   /* Rate limit window (seconds) */
    kline_time = 7;          /* Default KLINE duration (days, 0 = permanent) */
    commit_interval = 5;     /* Database save interval (minutes) */
    default_clone_allowed = 5;
    default_clone_warn = 4;
    clone_identified_increase_limit;
    uplink_sendq_limit = 1048576;  /* 1 MB send queue */
    language = "en";
    immune_level = immune;
    show_entity_id;
    load_database_mdeps;
    match_masks_through_vhost;
};

​

Logging

logfile "/dev/stdout" { debug; };

Note: The ATHEME_LOG_LEVEL variable is defined in .env.example but is not actually consumed by the config template. The log level is hardcoded to debug in the template. To change the log level, edit the logfile directive in atheme.conf.template directly.

/* Uncomment to log to IRC channels */
#logfile "#services" { debug; };
#logfile "!snotices" { debug; };

​

Operator classes

​

ircop

• User management: auspex (see hidden info), admin, sendpass, vhost, mark
• Channel management: auspex, admin, cmodes, joinstaffonly
• General: auspex, helper, viewprivs, flood bypass
• OperServ: omode, akill, jupe, global
• Group: auspex, admin

​

sra (Services Root Administrator)

• User: exceedlimits, hold, regnolimit
• General: metadata, admin
• OperServ: noop, grant
• Requires IRC operator status (needoper)

/msg OperServ SOPER ADD <account> sra

​

DNSBL configuration

proxyscan {
    blacklists {
        "dnsbl.dronebl.org";
        "rbl.efnetrbl.org";
        "tor.efnet.org";
        "dnsbl.tornevall.org";
        "bl.spamcop.net";
    };
    dnsbl_action = kline;  /* Automatically KLINE users matching a DNSBL */
};

​

Known issues and audit notes

• ATHEME_UPLINK_SSL_PORT — defined in .env.example as 6900 but never consumed by any template or compose file. The uplink uses plaintext on port 6901 (safe because it is localhost-only within the shared network namespace).
• ATHEME_LOG_LEVEL — defined in .env.example as all but not referenced in the config template. Log level is hardcoded.
• ATHEME_CHANFIX_* — four variables defined for ChanFix but only used in a commented-out config block. ChanFix is disabled by default.
• ATHEME_VERSION — set to master in .env.example. Consider pinning to a specific commit or tag for production stability.

​

Related pages

• Atheme Overview — architecture, service bots, and how Atheme fits in the stack
• Atheme Operations — service commands for NickServ, ChanServ, OperServ, and database management
• IRC Configuration — UnrealIRCd config including the services uplink and link password
• Environment Variables Reference — complete variable reference including all ATHEME_* variables
• Security — secret management and credential rotation for IRC_SERVICES_PASSWORD