default.yaml

# This is the default config file for Ergo.
# It contains recommended defaults for all settings, including some behaviors
# that differ from conventional ircd+services setups. See traditional.yaml
# for a config with more "mainstream" behavior.
#
# If you are setting up a new Ergo server, you should copy this file
# to a new one named 'ircd.yaml', then look through the file to see which
# settings you want to customize. If you don't understand a setting, or
# aren't sure what behavior you want, most of the defaults are fine
# to start with (you can change them later, even on a running server).
# However, there are a few that you should probably change up front:
# 1. network.name (a human-readable name that identifies your network,
#    no spaces or special characters) and server.name (consider using the
#    domain name of your server)
# 2. if you have valid TLS certificates (for example, from letsencrypt.org),
#    you should enable them in server.listeners in place of the default
#    self-signed certificates
# 3. the operator password in the 'opers' section
# 4. by default, message history is enabled, using in-memory history storage
#    and with messages expiring after 7 days. depending on your needs, you may
#    want to disable history entirely, remove the expiration time, switch to
#    persistent history stored in MySQL, or do something else entirely. See
#    the 'history' section of the config.

# network configuration
network:
    # name of the network
    name: ErgoTest

# server configuration
server:
    # server name
    name: ergo.test

    # addresses to listen on
    listeners:
        # The standard plaintext port for IRC is 6667. Allowing plaintext over the
        # public Internet poses serious security and privacy issues. Accordingly,
        # we recommend using plaintext only on local (loopback) interfaces:
        "127.0.0.1:6667": # (loopback ipv4, localhost-only)
        "[::1]:6667":     # (loopback ipv6, localhost-only)
        # If you need to serve plaintext on public interfaces, comment out the above
        # two lines and uncomment the line below (which listens on all interfaces):
        # ":6667":
        # Alternately, if you have a TLS certificate issued by a recognized CA,
        # you can configure port 6667 as an STS-only listener that only serves
        # "redirects" to the TLS port, but doesn't allow chat. See the manual
        # for details.

        # The standard SSL/TLS port for IRC is 6697. This will listen on all interfaces:
        ":6697":
            # this is a standard TLS configuration with a single certificate;
            # see the manual for instructions on how to configure SNI
            tls:
                cert: fullchain.pem
                key: privkey.pem
            # 'proxy' should typically be false. It's for cloud load balancers that
            # always send a PROXY protocol header ahead of the connection. See the
            # manual ("Reverse proxies") for more details.
            proxy: false
            # set the minimum TLS version:
            min-tls-version: 1.2

        # Example of a Unix domain socket for proxying:
        # "/tmp/ergo_sock":

        # Example of a Tor listener: any connection that comes in on this listener will
        # be considered a Tor connection. It is strongly recommended that this listener
        # *not* be on a public interface --- it should be on 127.0.0.0/8 or unix domain:
        # "/hidden_service_sockets/ergo_tor_sock":
        #     tor: true

        # Example of a WebSocket listener:
        # ":8097":
        #     websocket: true
        #     tls:
        #         cert: fullchain.pem
        #         key: privkey.pem

    # sets the permissions for Unix listen sockets. on a typical Linux system,
    # the default is 0775 or 0755, which prevents other users/groups from connecting
    # to the socket. With 0777, it behaves like a normal TCP socket
    # where anyone can connect.
    unix-bind-mode: 0777

    # configure the behavior of Tor listeners (ignored if you didn't enable any):
    tor-listeners:
        # if this is true, connections from Tor must authenticate with SASL
        require-sasl: false

        # what hostname should be displayed for Tor connections?
        vhost: "tor-network.onion"

        # allow at most this many connections at once (0 for no limit):
        max-connections: 64

        # connection throttling (limit how many connection attempts are allowed at once):
        throttle-duration: 10m
        # set to 0 to disable throttling:
        max-connections-per-duration: 64

    # strict transport security, to get clients to automagically use TLS
    # (irrelevant in the recommended configuration, with no public plaintext listener)
    sts:
        # whether to advertise STS
        #
        # to stop advertising STS, leave this enabled and set 'duration' below to "0". this will
        # advertise to connecting users that the STS policy they have saved is no longer valid
        enabled: false

        # how long clients should be forced to use TLS for.
        # setting this to a too-long time will mean bad things if you later remove your TLS.
        # the default duration below is 1 month, 2 days and 5 minutes.
        duration: 1mo2d5m

        # tls port - you should be listening on this port above
        port: 6697

        # should clients include this STS policy when they ship their inbuilt preload lists?
        preload: false

    websockets:
        # Restrict the origin of WebSocket connections by matching the "Origin" HTTP
        # header. This setting causes ergo to reject websocket connections unless
        # they originate from a page on one of the whitelisted websites in this list.
        # This prevents malicious websites from making their visitors connect to your
        # ergo instance without their knowledge. An empty list means there are no
        # restrictions.
        allowed-origins:
            # - "https://ergo.chat"
            # - "https://*.ergo.chat"

    # casemapping controls what kinds of strings are permitted as identifiers (nicknames,
    # channel names, account names, etc.), and how they are normalized for case.
    # the recommended default is 'ascii' (traditional ASCII-only identifiers).
    # the other options are 'precis', which allows UTF8 identifiers that are "sane"
    # (according to UFC 8265), with additional mitigations for homoglyph attacks,
    # 'permissive', which allows identifiers containing unusual characters like
    # emoji, at the cost of increased vulnerability to homoglyph attacks and potential
    # client compatibility problems, and the legacy mappings 'rfc1459' and
    # 'rfc1459-strict'. we recommend leaving this value at its default;
    # however, note that changing it once the network is already up and running is
    # problematic.
    casemapping: "ascii"

    # enforce-utf8 controls whether the server will preemptively discard non-UTF8
    # messages (since they cannot be relayed to websocket clients), or will allow
    # them and relay them to non-websocket clients (as in traditional IRC).
    enforce-utf8: true

    # whether to look up user hostnames with reverse DNS. there are 3 possibilities:
    # 1. lookup-hostnames enabled, IP cloaking disabled; users will see each other's hostnames
    # 2. lookup-hostnames disabled, IP cloaking disabled; users will see each other's numeric IPs
    # 3. [the default] IP cloaking enabled; users will see cloaked hostnames
    lookup-hostnames: false
    # whether to confirm hostname lookups using "forward-confirmed reverse DNS", i.e., for
    # any hostname returned from reverse DNS, resolve it back to an IP address and reject it
    # unless it matches the connecting IP
    forward-confirm-hostnames: true

    # use ident protocol to get usernames
    check-ident: false

    # ignore the supplied user/ident string from the USER command, always setting user/ident
    # to the following literal value; this can potentially reduce confusion and simplify bans.
    # the value must begin with a '~' character. comment out / omit to disable:
    coerce-ident: '~u'

    # 'password' allows you to require a global, shared password (the IRC `PASS` command)
    # to connect to the server. for operator passwords, see the `opers` section of the
    # config. for a more secure way to create a private server, see the `require-sasl`
    # section. you must hash the password with `ergo genpasswd`, then enter the hash here:
    #password: "$2a$04$0123456789abcdef0123456789abcdef0123456789abcdef01234"

    # motd filename
    # if you change the motd, you should move it to ircd.motd
    motd: ergo.motd

    # motd formatting codes
    # if this is true, the motd is escaped using formatting codes like $c, $b, and $i
    motd-formatting: true

    # send a configurable notice to clients immediately after they connect,
    # as a way of detecting open proxies
    #initial-notice: "*** Welcome to the Ergo IRC server"

    # idle timeouts for inactive clients
    idle-timeouts:
        # give the client this long to complete connection registration (i.e. the initial
        # IRC handshake, including capability negotiation and SASL)
        registration: 60s
        # if the client hasn't sent anything for this long, send them a PING
        ping: 1m30s
        # if the client hasn't sent anything for this long (including the PONG to the
        # above PING), disconnect them
        disconnect: 2m30s

    # relaying using the RELAYMSG command
    relaymsg:
        # is relaymsg enabled at all?
        enabled: true

        # which character(s) are reserved for relayed nicks?
        separators: "/"

        # can channel operators use RELAYMSG in their channels?
        # our implementation of RELAYMSG makes it safe for chanops to use without the
        # possibility of real users being silently spoofed
        available-to-chanops: true

    # IPs/CIDRs the PROXY command can be used from
    # This should be restricted to localhost (127.0.0.1/8, ::1/128, and unix sockets).
    # Unless you have a good reason. you should also add these addresses to the
    # connection limits and throttling exemption lists.
    proxy-allowed-from:
        - localhost
        # - "192.168.1.1"
        # - "192.168.10.1/24"

    # controls the use of the WEBIRC command (by IRC<->web interfaces, bouncers and similar)
    webirc:
        # one webirc block -- should correspond to one set of gateways
        -
            # SHA-256 fingerprint of the TLS certificate the gateway must use to connect
            # (comment this out to use passwords only)
            certfp: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"

            # password the gateway uses to connect, made with `ergo genpasswd`
            password: "$2a$04$abcdef0123456789abcdef0123456789abcdef0123456789abcde"

            # IPs/CIDRs that can use this webirc command
            # you should also add these addresses to the connection limits and throttling exemption lists
            hosts:
                - localhost
                # - "192.168.1.1"
                # - "192.168.10.1/24"

            # whether to accept the hostname parameter on the WEBIRC line as the IRC hostname
            # (the default/recommended Ergo configuration will use cloaks instead)
            accept-hostname: false

    # maximum length of clients' sendQ in bytes
    # this should be big enough to hold bursts of channel/direct messages
    max-sendq: 96k

    # compatibility with legacy clients
    compatibility:
        # many clients require that the final parameter of certain messages be an
        # RFC1459 trailing parameter, i.e., prefixed with :, whether or not this is
        # actually required. this forces Ergo to send those parameters
        # as trailings. this is recommended unless you're testing clients for conformance;
        # defaults to true when unset for that reason.
        force-trailing: true

        # some clients (ZNC 1.6.x and lower, Pidgin 2.12 and lower) do not
        # respond correctly to SASL messages with the server name as a prefix:
        # https://github.com/znc/znc/issues/1212
        # this works around that bug, allowing them to use SASL.
        send-unprefixed-sasl: true

        # traditionally, IRC servers will truncate and send messages that are
        # too long to be relayed intact. this behavior can be disabled by setting
        # allow-truncation to false, in which case Ergo will reject the message
        # and return an error to the client. (note that this option defaults to true
        # when unset.)
        allow-truncation: false

    # IP-based DoS protection
    ip-limits:
        # whether to limit the total number of concurrent connections per IP/CIDR
        count: true
        # maximum concurrent connections per IP/CIDR
        max-concurrent-connections: 16

        # whether to restrict the rate of new connections per IP/CIDR
        throttle: true
        # how long to keep track of connections for
        window: 10m
        # maximum number of new connections per IP/CIDR within the given duration
        max-connections-per-window: 32

        # how wide the CIDR should be for IPv4 (a /32 is a fully specified IPv4 address)
        cidr-len-ipv4: 32
        # how wide the CIDR should be for IPv6 (a /64 is the typical prefix assigned
        # by an ISP to an individual customer for their LAN)
        cidr-len-ipv6: 64

        # IPs/networks which are exempted from connection limits
        exempted:
            - "localhost"
            # - "192.168.1.1"
            # - "2001:0db8::/32"

        # custom connection limits for certain IPs/networks.
        custom-limits:
            #"irccloud":
            #    nets:
            #        - "192.184.9.108"  # highgate.irccloud.com
            #        - "192.184.9.110"  # ealing.irccloud.com
            #        - "192.184.9.112"  # charlton.irccloud.com
            #        - "192.184.10.118" # brockwell.irccloud.com
            #        - "192.184.10.9"   # tooting.irccloud.com
            #        - "192.184.8.73"   # hathersage.irccloud.com
            #        - "192.184.8.103"  # stonehaven.irccloud.com
            #        - "5.254.36.57"    # tinside.irccloud.com
            #        - "5.254.36.56/29" # additional ipv4 net
            #        - "2001:67c:2f08::/48"
            #        - "2a03:5180:f::/64"
            #    max-concurrent-connections: 2048
            #    max-connections-per-window: 2048

    # pluggable IP ban mechanism, via subprocess invocation
    # this can be used to check new connections against a DNSBL, for example
    # see the manual for details on how to write an IP ban checking script
    ip-check-script:
        enabled: false
        command: "/usr/local/bin/check-ip-ban"
        # constant list of args to pass to the command; the actual query
        # and result are transmitted over stdin/stdout:
        args: []
        # alternatively, pass the input to a persistent process over unix domain socket:
        #socket: "/tmp/ergo_ip_check_sidecar"
        # timeout for process execution, after which we send a SIGTERM:
        timeout: 9s
        # how long after the SIGTERM before we follow up with a SIGKILL:
        kill-timeout: 1s
        # how many scripts are allowed to run at once? 0 for no limit:
        max-concurrency: 64
        # if true, only check anonymous connections (not logged into an account)
        # at the very end of the handshake:
        exempt-sasl: false

    # IP cloaking hides users' IP addresses from other users and from channel admins
    # (but not from server admins), while still allowing channel admins to ban
    # offending IP addresses or networks. In place of hostnames derived from reverse
    # DNS, users see fake domain names like pwbs2ui4377257x8.irc. These names are
    # generated deterministically from the underlying IP address, but if the underlying
    # IP is not already known, it is infeasible to recover it from the cloaked name.
    # If you disable this, you should probably enable lookup-hostnames in its place.
    ip-cloaking:
        # whether to enable IP cloaking
        enabled: true

        # whether to use these cloak settings (specifically, `netname` and `num-bits`)
        # to produce unique hostnames for always-on clients. you can enable this even if
        # you disabled IP cloaking for normal clients above. if this is disabled,
        # always-on clients will all have an identical hostname (the server name).
        enabled-for-always-on: true

        # fake TLD at the end of the hostname, e.g., pwbs2ui4377257x8.irc
        # you may want to use your network name here
        netname: "irc"

        # the cloaked hostname is derived only from the CIDR (most significant bits
        # of the IP address), up to a configurable number of bits. this is the
        # granularity at which bans will take effect for IPv4. Note that changing
        # this value will invalidate any stored bans.
        cidr-len-ipv4: 32

        # analogous granularity for IPv6
        cidr-len-ipv6: 64

        # number of bits of hash output to include in the cloaked hostname.
        # more bits means less likelihood of distinct IPs colliding,
        # at the cost of a longer cloaked hostname. if this value is set to 0,
        # all users will receive simply `netname` as their cloaked hostname.
        num-bits: 64

    # secure-nets identifies IPs and CIDRs which are secure at layer 3,
    # for example, because they are on a trusted internal LAN or a VPN.
    # plaintext connections from these IPs and CIDRs will be considered
    # secure (clients will receive the +Z mode and be allowed to resume
    # or reattach to secure connections). note that loopback IPs are always
    # considered secure:
    secure-nets:
        # - "10.0.0.0/8"

    # allow attempts to OPER with a password at most this often. defaults to
    # 10 seconds when unset.
    oper-throttle: 10s

    # Ergo will write files to disk under certain circumstances, e.g.,
    # CPU profiling or data export. by default, these files will be written
    # to the working directory. set this to customize:
    #output-path: "/home/ergo/out"

    # the hostname used by "services", e.g., NickServ, defaults to "localhost",
    # e.g., `NickServ!NickServ@localhost`. uncomment this to override:
    #override-services-hostname: "example.network"

    # in a "closed-loop" system where you control the server and all the clients,
    # you may want to increase the maximum (non-tag) length of an IRC line from
    # the default value of 512. DO NOT change this on a public server:
    #max-line-len: 512

    # send all 0's as the LUSERS (user counts) output to non-operators; potentially useful
    # if you don't want to publicize how popular the server is
    suppress-lusers: false

    # publish additional key-value pairs in ISUPPORT (the 005 numeric).
    # keys that collide with a key published by Ergo will be silently ignored.
    additional-isupport:
        #"draft/FILEHOST": "https://example.com/filehost"
        #"draft/bazbat": "" # empty string means no value

    # optionally map command alias names to existing ergo commands. most deployments
    # should ignore this.
    #command-aliases:
        #"UMGEBUNG": "AMBIANCE"

# account options
accounts:
    # is account authentication enabled, i.e., can users log into existing accounts?
    authentication-enabled: true

    # account registration
    registration:
        # can users register new accounts for themselves? if this is false, operators with
        # the `accreg` capability can still create accounts with `/NICKSERV SAREGISTER`
        enabled: true

        # can users use the REGISTER command to register before fully connecting?
        allow-before-connect: true

        # global throttle on new account creation
        throttling:
            enabled: true
            # window
            duration: 10m
            # number of attempts allowed within the window
            max-attempts: 30

        # this is the bcrypt cost we'll use for account passwords
        # (note that 4 is the lowest value allowed by the bcrypt library)
        bcrypt-cost: 4

        # length of time a user has to verify their account before it can be re-registered
        verify-timeout: "32h"

        # options for email verification of account registrations
        email-verification:
            enabled: false
            sender: "admin@my.network"
            require-tls: true
            helo-domain: "my.network" # defaults to server name if unset
            # set to `tcp4` to force sending over IPv4, `tcp6` to force IPv6:
            # protocol: "tcp4"
            # set to force a specific source/local IPv4 or IPv6 address:
            # local-address: "1.2.3.4"
            # options to enable DKIM signing of outgoing emails (recommended, but
            # requires creating a DNS entry for the public key):
            # dkim:
            #     domain: "my.network"
            #     selector: "20200229"
            #     key-file: "dkim.pem"
            # to use an MTA/smarthost instead of sending email directly:
            # mta:
            #     server: localhost
            #     port: 25
            #     username: "admin"
            #     password: "hunter2"
            #     implicit-tls: false # TLS from the first byte, typically on port 465
            # addresses that are not accepted for registration:
            address-blacklist:
            #    - "*@mailinator.com"
            address-blacklist-syntax: "glob" # change to "regex" for regular expressions
            # file of newline-delimited address blacklist entries (no enclosing quotes)
            # in the above syntax (i.e. either globs or regexes). supersedes
            # address-blacklist if set:
            # address-blacklist-file: "/path/to/address-blacklist-file"
            timeout: 60s
            # email-based password reset:
            password-reset:
                enabled: false
                # time before we allow resending the email
                cooldown: 1h
                # time for which a password reset code is valid
                timeout: 1d

    # throttle account login attempts (to prevent either password guessing, or DoS
    # attacks on the server aimed at forcing repeated expensive bcrypt computations)
    login-throttling:
        enabled: true

        # window
        duration:  1m

        # number of attempts allowed within the window
        max-attempts: 3

    # some clients (notably Pidgin and Hexchat) offer only a single password field,
    # which makes it impossible to specify a separate server password (for the PASS
    # command) and SASL password. if this option is set to true, a client that
    # successfully authenticates with SASL will not be required to send
    # PASS as well, so it can be configured to authenticate with SASL only.
    skip-server-password: false

    # enable login to accounts via the PASS command, e.g., PASS account:password
    # this is useful for compatibility with old clients that don't support SASL
    login-via-pass-command: true

    # advertise the SCRAM-SHA-256 authentication method. set to false in case of
    # compatibility issues with certain clients:
    advertise-scram: true

    # require-sasl controls whether clients are required to have accounts
    # (and sign into them using SASL) to connect to the server
    require-sasl:
        # if this is enabled, all clients must authenticate with SASL while connecting.
        # WARNING: for a private server, you MUST set accounts.registration.enabled
        # to false as well, in order to prevent non-administrators from registering
        # accounts.
        enabled: false

        # IPs/CIDRs which are exempted from the account requirement
        exempted:
            - "localhost"
            # - '10.10.0.0/16'

    # nick-reservation controls how, and whether, nicknames are linked to accounts
    nick-reservation:
        # is there any enforcement of reserved nicknames?
        enabled: true

        # how many nicknames, in addition to the account name, can be reserved?
        # (note that additional nicks are unusable under force-nick-equals-account
        # or if the client is always-on)
        additional-nick-limit: 0

        # method describes how nickname reservation is handled
        #   strict:   users must already be logged in to their account (via
        #             SASL, PASS account:password, or /NickServ IDENTIFY)
        #             in order to use their reserved nickname(s)
        #   optional: no enforcement by default, but allow users to opt in to
        #             the enforcement level of their choice
        method: strict

        # allow users to set their own nickname enforcement status, e.g.,
        # to opt out of strict enforcement
        allow-custom-enforcement: false

        # format for guest nicknames:
        # 1. these nicknames cannot be registered or reserved
        # 2. if a client is automatically renamed by the server,
        #    this is the template that will be used (e.g., Guest-nccj6rgmt97cg)
        # 3. if force-guest-format (see below) is enabled, clients without
        #    a registered account will have this template applied to their
        #    nicknames (e.g., 'katie' will become 'Guest-katie')
        guest-nickname-format: "Guest-*"

        # when enabled, forces users not logged into an account to use
        # a nickname matching the guest template. a caveat: this may prevent
        # users from choosing nicknames in scripts different from the guest
        # nickname format.
        force-guest-format: false

        # when enabled, forces users logged into an account to use the
        # account name as their nickname. when combined with strict nickname
        # enforcement, this lets users treat nicknames and account names
        # as equivalent for the purpose of ban/invite/exception lists.
        force-nick-equals-account: true

        # parallel setting to force-nick-equals-account: if true, this forbids
        # anonymous users (i.e., users not logged into an account) to change their
        # nickname after the initial connection is complete
        forbid-anonymous-nick-changes: false

    # multiclient controls whether Ergo allows multiple connections to
    # attach to the same client/nickname identity; this is part of the
    # functionality traditionally provided by a bouncer like ZNC
    multiclient:
        # when disabled, each connection must use a separate nickname (as is the
        # typical behavior of IRC servers). when enabled, a new connection that
        # has authenticated with SASL can associate itself with an existing
        # client
        enabled: true

        # if this is disabled, clients have to opt in to bouncer functionality
        # using nickserv or the cap system. if it's enabled, they can opt out
        # via nickserv
        allowed-by-default: true

        # whether to allow clients that remain on the server even
        # when they have no active connections. The possible values are:
        # "disabled", "opt-in", "opt-out", or "mandatory".
        always-on: "opt-in"

        # whether to mark always-on clients away when they have no active connections:
        auto-away: "opt-in"

        # QUIT always-on clients from the server if they go this long without connecting
        # (use 0 or omit for no expiration):
        #always-on-expiration: 90d

    # vhosts controls the assignment of vhosts (strings displayed in place of the user's
    # hostname/IP) by the HostServ service
    vhosts:
        # are vhosts enabled at all?
        enabled: true

        # maximum length of a vhost
        max-length: 64

        # regexp for testing the validity of a vhost
        # (make sure any changes you make here are RFC-compliant)
        valid-regexp: '^[0-9A-Za-z.\-_/]+$'

    # modes that are set by default when a user connects
    # if unset, no user modes will be set by default
    # +i is invisible (a user's channels are hidden from whois replies)
    # see  /QUOTE HELP umodes  for more user modes
    default-user-modes: +i

    # pluggable authentication mechanism, via subprocess invocation
    # see the manual for details on how to write an authentication plugin script
    auth-script:
        enabled: false
        command: "/usr/local/bin/authenticate-irc-user"
        # constant list of args to pass to the command; the actual authentication
        # data is transmitted over stdin/stdout:
        args: []
        # alternatively, pass the input to a persistent process over unix domain socket:
        #socket: "/tmp/ergo_auth_sidecar"
        # should we automatically create users if the plugin returns success?
        autocreate: true
        # timeout for process execution, after which we send a SIGTERM:
        timeout: 9s
        # how long after the SIGTERM before we follow up with a SIGKILL:
        kill-timeout: 1s
        # how many scripts are allowed to run at once? 0 for no limit:
        max-concurrency: 64

    # support for login via OAuth2 bearer tokens
    oauth2:
        enabled: false
        # should we automatically create users on presentation of a valid token?
        autocreate: true
        # enable this to use auth-script for validation:
        auth-script: false
        introspection-url: "https://example.com/api/oidc/introspection"
        introspection-timeout: 10s
        # omit for auth method `none`; required for auth method `client_secret_basic`:
        client-id: "ergo"
        client-secret: "4TA0I7mJ3fUUcW05KJiODg"

    # support for login via JWT bearer tokens
    jwt-auth:
        enabled: false
        # should we automatically create users on presentation of a valid token?
        autocreate: true
        # any of these token definitions can be accepted, allowing for key rotation
        tokens:
            -
                algorithm: "hmac" # either 'hmac', 'rsa', or 'eddsa' (ed25519)
                # hmac takes a symmetric key, rsa and eddsa take PEM-encoded public keys;
                # either way, the key can be specified either as a YAML string:
                key: "nANiZ1De4v6WnltCHN2H7Q"
                # or as a path to the file containing the key:
                #key-file: "jwt_pubkey.pem"
                # list of JWT claim names to search for the user's account name (make sure the format
                # is what you expect, especially if using "sub"):
                account-claims: ["preferred_username"]
                # if a claim is formatted as an email address, require it to have the following domain,
                # and then strip off the domain and use the local-part as the account name:
                #strip-domain: "example.com"
                # optional list of `aud` claims that are acceptable
                # (if omitted, the aud claim is not validated):
                #validate-aud: ["irc.mydomain.com"]

# channel options
channels:
    # modes that are set when new channels are created
    # +n is no-external-messages, +t is op-only-topic,
    # +C is no CTCPs (besides ACTION)
    # see  /QUOTE HELP cmodes  for more channel modes
    default-modes: +ntC

    # how many channels can a client be in at once?
    max-channels-per-client: 100

    # if this is true, new channels can only be created by operators with the
    # `chanreg` operator capability
    operator-only-creation: false

    # channel registration - requires an account
    registration:
        # can users register new channels?
        enabled: true

        # restrict new channel registrations to operators only?
        # (operators can then transfer channels to regular users using /CS TRANSFER)
        operator-only: false

        # how many channels can each account register?
        max-channels-per-account: 15

    # as a crude countermeasure against spambots, anonymous connections younger
    # than this value will get an empty response to /LIST (a time period of 0 disables)
    list-delay: 0s

    # INVITE to an invite-only channel expires after this amount of time
    # (0 or omit for no expiration):
    invite-expiration: 24h

    # channels that new clients will automatically join. this should be used with
    # caution, since traditional IRC users will likely view it as an antifeature.
    # it may be useful in small community networks that have a single "primary" channel:
    #auto-join:
    #    - "#lounge"

# operator classes:
# an operator has a single "class" (defining a privilege level), which can include
# multiple "capabilities" (defining privileged actions they can take). all
# currently available operator capabilities are associated with either the
# 'chat-moderator' class (less privileged) or the 'server-admin' class (full
# privileges) below: you can mix and match to create new classes.
oper-classes:
    # chat moderator: can ban/unban users from the server, join channels,
    # fix mode issues and sort out vhosts.
    "chat-moderator":
        # title shown in WHOIS
        title: Chat Moderator

        # capability names
        capabilities:
            - "kill"      # disconnect user sessions
            - "ban"       # ban IPs, CIDRs, NUH masks, and suspend accounts (UBAN / DLINE / KLINE)
            - "nofakelag" # exempted from "fakelag" restrictions on rate of message sending
            - "relaymsg"  # use RELAYMSG in any channel (see the `relaymsg` config block)
            - "vhosts"    # add and remove vhosts from users
            - "sajoin"    # join arbitrary channels, including private channels
            - "samode"    # modify arbitrary channel and user modes
            - "snomasks"  # subscribe to arbitrary server notice masks
            - "roleplay"  # use the (deprecated) roleplay commands in any channel

    # server admin: has full control of the ircd, including nickname and
    # channel registrations
    "server-admin":
        # title shown in WHOIS
        title: Server Admin

        # oper class this extends from
        extends: "chat-moderator"

        # capability names
        capabilities:
            - "rehash"       # rehash the server, i.e. reload the config at runtime
            - "accreg"       # modify arbitrary account registrations
            - "chanreg"      # modify arbitrary channel registrations
            - "history"      # modify or delete history messages
            - "defcon"       # use the DEFCON command (restrict server capabilities)
            - "massmessage"  # message all users on the server
            - "metadata"     # modify arbitrary metadata on channels and users

# ircd operators
opers:
    # default operator named 'admin'; log in with /OPER admin <password>
    admin:
        # which capabilities this oper has access to
        class: "server-admin"

        # traditionally, operator status is visible to unprivileged users in
        # WHO and WHOIS responses. this can be disabled with 'hidden'.
        hidden: true

        # custom whois line (if `hidden` is enabled, visible only to other operators)
        whois-line: is the server administrator

        # custom hostname (ignored if `hidden` is enabled)
        #vhost: "staff"

        # modes are modes to auto-set upon opering-up. uncomment this to automatically
        # enable snomasks ("server notification masks" that alert you to server events;
        # see `/quote help snomasks` while opered-up for more information):
        #modes: +is acdjknoqtuxv

        # operators can be authenticated either by password (with the /OPER command),
        # or by certificate fingerprint, or both. if a password hash is set, then a
        # password is required to oper up (e.g., /OPER dan mypassword). to generate
        # the hash, use `ergo genpasswd`.
        password: "$2a$04$0123456789abcdef0123456789abcdef0123456789abcdef01234"

        # if a SHA-256 certificate fingerprint is configured here, then it will be
        # required to /OPER. if you comment out the password hash above, then you can
        # /OPER without a password.
        #certfp: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
        # if 'auto' is set (and no password hash is set), operator permissions will be
        # granted automatically as soon as you connect with the right fingerprint.
        #auto: true

    # example of a moderator named 'alice'
    # (log in with /OPER alice <password>):
    #alice:
    #    class: "chat-moderator"
    #    whois-line: "can help with moderation issues!"
    #    password: "$2a$04$0123456789abcdef0123456789abcdef0123456789abcdef01234"

# logging, takes inspiration from Insp
logging:
    -
        # how to log these messages
        #
        #   file    log to a file
        #   stdout  log to stdout
        #   stderr  log to stderr
        #   (you can specify multiple methods, e.g., to log to both stderr and a file)
        method: stderr

        # filename to log to, if file method is selected
        # filename: ircd.log

        # type(s) of logs to keep here. you can use - to exclude those types
        #
        # exclusions take precedent over inclusions, so if you exclude a type it will NEVER
        # be logged, even if you explicitly include it
        #
        # useful types include:
        #   *               everything (usually used with excluding some types below)
        #   server          server startup, rehash, and shutdown events
        #   accounts        account registration and authentication
        #   channels        channel creation and operations
        #   opers           oper actions, authentication, etc
        #   services        actions related to NickServ, ChanServ, etc.
        #   internal        unexpected runtime behavior, including potential bugs
        #   userinput       raw lines sent by users
        #   useroutput      raw lines sent to users
        type: "* -userinput -useroutput"

        # one of: debug info warn error
        level: info
    #-
    #   # example of a file log that avoids logging IP addresses
    #   method: file
    #   filename: ircd.log
    #   type: "* -userinput -useroutput -connect-ip"
    #   level: debug

# debug options
debug:
    # when enabled, Ergo will attempt to recover from certain kinds of
    # client-triggered runtime errors that would normally crash the server.
    # this makes the server more resilient to DoS, but could result in incorrect
    # behavior. deployments that would prefer to "start from scratch", e.g., by
    # letting the process crash and auto-restarting it with systemd, can set
    # this to false.
    recover-from-errors: true

    # optionally expose a pprof http endpoint: https://golang.org/pkg/net/http/pprof/
    # it is strongly recommended that you don't expose this on a public interface;
    # if you need to access it remotely, you can use an SSH tunnel.
    # set to `null`, "", leave blank, or omit to disable
    # pprof-listener: "localhost:6060"

# lock file preventing multiple instances of Ergo from accidentally being
# started at once. comment out or set to the empty string ("") to disable.
# this path is relative to the working directory; if your datastore.path
# is absolute, you should use an absolute path here as well.
lock-file: "ircd.lock"

# datastore configuration
datastore:
    # path to the database file (used to store account and channel registrations):
    path: ircd.db

    # if the database schema requires an upgrade, `autoupgrade` will attempt to
    # perform it automatically on startup. the database will be backed
    # up, and if the upgrade fails, the original database will be restored.
    autoupgrade: true

    # connection information for MySQL (currently only used for persistent history):
    mysql:
        enabled: false
        host: "localhost"
        port: 3306
        # if socket-path is set, it will be used instead of host:port
        #socket-path: "/var/run/mysqld/mysqld.sock"
        user: "ergo"
        password: "hunter2"
        history-database: "ergo_history"
        timeout: 3s
        max-conns: 4
        # this may be necessary to prevent middleware from closing your connections:
        #conn-max-lifetime: 180s

    # connection information for PostgreSQL (currently only used for persistent history)
    postgresql:
        enabled: false
        host: "localhost"
        port: 5432
        # if socket-path is set, it will be used instead of host:port
        # PostgreSQL uses the socket directory, not the socket file path
        #socket-path: "/var/run/postgresql"
        # PostgreSQL SSL/TLS configuration:
        ssl-mode: "disable" # options: disable, require, verify-ca, verify-full
        #ssl-cert: "/path/to/client-cert.pem"
        #ssl-key: "/path/to/client-key.pem"
        #ssl-root-cert: "/path/to/ca-cert.pem"
        user: "ergo"
        password: "hunter2"
        history-database: "ergo_history"
        # uri takes a postgresql:// (libpq) URI, overriding the above parameters if present:
        # uri: "postgresql://ergo:hunter2@localhost/ergo_history"
        timeout: 3s
        max-conns: 4
        # this may be necessary to prevent middleware from closing your connections:
        #conn-max-lifetime: 180s
        # application name shown in pg_stat_activity for operational visibility:
        #application-name: "ergo"
        # timeout for establishing initial connections to PostgreSQL:
        #connect-timeout: 10s

    # connection information for SQLite (currently only used for persistent history)
    sqlite:
        enabled: false
        # path to the SQLite database file
        database-path: "ergo_history.db"
        # timeout when waiting for write lock
        busy-timeout: 5s
        # maximum concurrent connections
        max-conns: 1

# languages config
languages:
    # whether to load languages
    enabled: true

    # default language to use for new clients
    # 'en' is the default English language in the code
    default: en

    # which directory contains our language files
    path: languages

# limits - these need to be the same across the network
limits:
    # nicklen is the max nick length allowed
    nicklen: 32

    # identlen is the max ident length allowed
    identlen: 20

    # realnamelen is the maximum realname length allowed
    realnamelen: 150

    # channellen is the max channel length allowed
    channellen: 64

    # awaylen is the maximum length of an away message
    awaylen: 390

    # kicklen is the maximum length of a kick message
    kicklen: 390

    # topiclen is the maximum length of a channel topic
    topiclen: 390

    # maximum number of monitor entries a client can have
    monitor-entries: 100

    # whowas entries to store
    whowas-entries: 100

    # maximum length of channel lists (beI modes)
    chan-list-modes: 100

    # maximum number of messages to accept during registration (prevents
    # DoS / resource exhaustion attacks):
    registration-messages: 1024

    # message length limits for the new multiline cap
    multiline:
        max-bytes: 4096 # 0 means disabled
        max-lines: 100  # 0 means no limit

# fakelag: prevents clients from spamming commands too rapidly
fakelag:
    # whether to enforce fakelag
    enabled: true

    # time unit for counting command rates
    window: 1s

    # clients can send this many commands without fakelag being imposed
    burst-limit: 5

    # once clients have exceeded their burst allowance, they can send only
    # this many commands per `window`:
    messages-per-window: 2

    # client status resets to the default state if they go this long without
    # sending any commands:
    cooldown: 2s

    # exempt a certain number of command invocations per session from fakelag;
    # this is to speed up "resynchronization" of client state during reattach
    command-budgets:
        "CHATHISTORY": 16
        "MARKREAD":    16
        "MONITOR":     1
        "WHO":         4
        "WEBPUSH":     1

# the roleplay commands are semi-standardized extensions to IRC that allow
# sending and receiving messages from pseudo-nicknames. this can be used either
# for actual roleplaying, or for bridging IRC with other protocols.
roleplay:
    # are roleplay commands enabled at all? (channels and clients still have to
    # opt in individually with the +E mode)
    enabled: false

    # require the "roleplay" oper capability to send roleplay messages?
    require-oper: false

    # require channel operator permissions to send roleplay messages?
    require-chanops: false

    # add the real nickname, in parentheses, to the end of every roleplay message?
    add-suffix: true

    # allow customizing the NUH's sent for NPC and SCENE commands
    # NPC: the first %s is the NPC name, the second is the user's real nick
    #npc-nick-mask: "*%s*!%s@npc.fakeuser.invalid"
    # SCENE: the %s is the client's real nick
    #scene-nick-mask: "=Scene=!%s@npc.fakeuser.invalid"

# external services can integrate with the ircd using JSON Web Tokens (https://jwt.io).
# in effect, the server can sign a token attesting that the client is present on
# the server, is a member of a particular channel, etc.
extjwt:
    # # default service config (for `EXTJWT #channel`).
    # # expiration time for the token:
    # expiration: 45s
    # algorithm: "hmac" # either 'hmac', 'rsa', or 'eddsa' (ed25519)
    # # hmac takes a symmetric key, rsa and eddsa take PEM-encoded private keys;
    # # either way, the key can be specified either as a YAML string:
    # key: "nANiZ1De4v6WnltCHN2H7Q"
    # # or as a path to the file containing the key:
    # #key-file: "jwt_privkey.pem"

    # # named services (for `EXTJWT #channel service_name`):
    # services:
    #     "jitsi":
    #         expiration: 30s
    #         algorithm: "hmac"
    #         key: "qmamLKDuOzIzlO8XqsGGewei_At11lewh6jtKfSTbkg"

# experimental draft/AUTHTOKEN mechanism
authtoken:
    enabled: false

    # only these IPs can verify tokens
    verification-ip-whitelist:
        - "localhost"

    #services:
    #   "FILEHOST":
    #       expiration: 5m
    #       url: "https://example.com/filehost"
    #       algorithm: "eddsa"
    #       key: "-----BEGIN PRIVATE KEY-----\nMC4CAQAwBQYDK2VwBCIEIHfpO1x835o9NIQA1kBkN7/Myd6wqE/m/EYJUHBC18hW\n-----END PRIVATE KEY-----"

# history message storage: this is used by CHATHISTORY, HISTORY, znc.in/playback,
# various autoreplay features, and the resume extension
history:
    # should we store messages for later playback?
    # by default, messages are stored in RAM only; they do not persist
    # across server restarts. however, you may want to understand how message
    # history interacts with the GDPR and/or any data privacy laws that apply
    # in your country and the countries of your users.
    enabled: true

    # if the in-memory backend is enabled for a channel, how many channel-specific events
    # (messages, joins, parts) should be retained?
    channel-length: 2048

    # if the in-memory backend is enabled for a user, how many direct messages
    # and notices should be retained?
    client-length: 256

    # how long should we try to preserve messages?
    # if `autoresize-window` is 0, the in-memory message buffers are preallocated to
    # their maximum length. if it is nonzero, the buffers are initially small and
    # are dynamically expanded up to the maximum length. if the buffer is full
    # and the oldest message is older than `autoresize-window`, then it will overwrite
    # the oldest message rather than resize; otherwise, it will expand if possible.
    autoresize-window: 3d

    # number of messages to automatically play back on channel join (0 to disable):
    autoreplay-on-join: 0

    # maximum number of CHATHISTORY messages that can be
    # requested at once (0 disables support for CHATHISTORY)
    chathistory-maxmessages: 1000

    # maximum number of messages that can be replayed at once during znc emulation
    # (znc.in/playback, or automatic replay on initial reattach to a persistent client):
    znc-maxmessages: 2048

    # options to delete old messages, or prevent them from being retrieved
    restrictions:
        # if this is set, messages older than this cannot be retrieved by anyone
        # (and will eventually be deleted from persistent storage, if that's enabled)
        expire-time: 1w

        # this restricts access to channel history (it can be overridden by channel
        # owners). options are: 'none' (no restrictions), 'registration-time'
        # (logged-in users cannot retrieve messages older than their account
        # registration date, and anonymous users cannot retrieve messages older than
        # their sign-on time, modulo the grace-period described below), and
        # 'join-time' (users cannot retrieve messages older than the time they
        # joined the channel, so only always-on clients can view history).
        query-cutoff: 'none'

        # if query-cutoff is set to 'registration-time', this allows retrieval
        # of messages that are up to 'grace-period' older than the above cutoff.
        # if you use 'registration-time', this is recommended to allow logged-out
        # users to query history after disconnections.
        grace-period: 1h

    # options to store history messages in a persistent database (MySQL, PostgreSQL
    # or SQLite). in order to enable any of this functionality, you must configure
    # one of those databases above. enabling persistence overrides the history
    # size limits above (`channel-length`, `client-length`, etc.); persistent
    # history has no limits other than those imposed by expire-time.
    persistent:
        enabled: false

        # store unregistered channel messages in the persistent database?
        unregistered-channels: false

        # for a registered channel, the channel owner can potentially customize
        # the history storage setting. as the server operator, your options are
        # 'disabled' (no persistent storage, regardless of per-channel setting),
        # 'opt-in', 'opt-out', and 'mandatory' (force persistent storage, ignoring
        # per-channel setting):
        registered-channels: "opt-out"

        # direct messages are only stored in the database for logged-in clients;
        # you can control how they are stored here (same options as above).
        # if you enable this, strict nickname reservation is strongly recommended
        # as well.
        direct-messages: "opt-out"

    # options to control how messages are stored and deleted:
    retention:
        # allow users to delete their own messages from history,
        # and channel operators to delete messages in their channel?
        allow-individual-delete: false

        # if persistent history is enabled, create additional index tables,
        # allowing deletion of JSON export of an account's messages. this
        # may be needed for compliance with data privacy regulations.
        enable-account-indexing: false

    # options to control storage of TAGMSG
    tagmsg-storage:
        # by default, should TAGMSG be stored?
        default: false

        # if `default` is false, store TAGMSG containing any of these tags:
        whitelist:
            - "+draft/react"
            - "+react"

        # if `default` is true, don't store TAGMSG containing any of these tags:
        #blacklist:
        #    - "+draft/typing"
        #    - "typing"

# whether to allow customization of the config at runtime using environment variables,
# e.g., ERGO__SERVER__MAX_SENDQ=128k. see the manual for more details.
allow-environment-overrides: true

# metadata support for setting key/value data on channels and nicknames.
metadata:
    # can clients store metadata?
    enabled: true
    # if this is true, only server operators with the `metadata` capability can edit metadata:
    operator-only-modification: false
    # how many keys can a client subscribe to?
    max-subs: 100
    # how many keys can be stored per entity?
    max-keys: 100
    # rate limiting for client metadata updates, which are expensive to process
    client-throttle:
        enabled: true
        duration: 2m
        max-attempts: 10

# experimental support for mobile push notifications
# see the manual for potential security, privacy, and performance implications.
# DO NOT enable if you are running a Tor or I2P hidden service (i.e. one
# with no public IP listeners, only Tor/I2P listeners).
webpush:
    # are push notifications enabled at all?
    enabled: false
    # request timeout for POST'ing the http notification
    timeout: 10s
    # delay sending the notification for this amount of time, then suppress it
    # if the client sent MARKREAD to indicate that it was read on another device
    delay: 0s
    # subscriber field for the VAPID JWT authorization:
    #subscriber: "https://your-website.com/"
    # maximum number of push subscriptions per user
    max-subscriptions: 4
    # expiration time for a push subscription; it must be renewed within this time
    # by the client reconnecting to IRC. we also detect whether the client is no longer
    # successfully receiving push messages.
    expiration: 14d

# HTTP API. we strongly recommend leaving this disabled unless you have a specific
# need for it.
api:
    # is the API enabled at all?
    enabled: false
    # listen address:
    listener: "127.0.0.1:8089"
    # serve over TLS (strongly recommended if the listener is public):
    #tls:
        #cert: fullchain.pem
        #key: privkey.pem
    # one or more static bearer tokens accepted for HTTP bearer authentication.
    # these must be strong, unique, high-entropy printable ASCII strings.
    # to generate a new token, use `ergo gentoken` or:
    # python3 -c "import secrets; print(secrets.token_urlsafe(32))"
    bearer-tokens:
        - "example"