# This is the default config file for Ergo.

# It contains recommended defaults for all settings, including some behaviors

# that differ from conventional ircds. See conventional.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 read the whole 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: {{ergo_network_name}}

# server configuration

server:

    # server name

    name: {{ergo_server_name}}

    # 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":

        #     tls:

        #         cert: fullchain.pem

        #         key: privkey.pem

        #         # 'proxy' should typically be false. It's only for Kubernetes-style load

        #         # balancing that does not terminate TLS, but sends an initial PROXY line

        #         # in plaintext.

        #         proxy: false

        # Example of a Unix domain socket for proxying:

        "/var/ergo/socket":

        # 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

    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 settings makes ergo reject every WebSocket connection,

        # except when it originates from one of the hosts in this list. Use this to

        # prevent malicious websites from making their visitors connect to ergo

        # without their knowledge. An empty list means that there are no restrictions.

        allowed-origins:

            # - "https://ergo.io"

            # - "https://*.ergo.io"

    # casemapping controls what kinds of strings are permitted as identifiers (nicknames,

    # channel names, account names, etc.), and how they are normalized for case.

    # with the recommended default of 'precis', utf-8 identifiers that are "sane"

    # (according to RFC 8265) are allowed, and the server additionally tries to protect

    # against confusable characters ("homoglyph attacks").

    # the other options are 'ascii' (traditional ASCII-only identifiers), and 'permissive',

    # which allows identifiers to contain unusual characters like emoji, but makes users

    # vulnerable to homoglyph attacks. unless you're really confident in your decision,

    # we recommend leaving this value at its default (changing it once the network is

    # already up and running is problematic).

    casemapping: "precis"

    # whether to look up user hostnames with reverse DNS.

    # (disabling this will expose user IPs instead of hostnames;

    # to make IP/hostname information private, see the ip-cloaking section)

    lookup-hostnames: true

    # 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

    # password to login to the server

    # generated using  "ergo genpasswd"

    #password: ""

    # motd filename

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

    motd: "/etc/ergo/motd"

    # motd formatting codes

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

    motd-formatting: true

    # addresses/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)

            fingerprint: "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"

            # password the gateway uses to connect, made with ergo genpasswd

            password: "$2a$04$abcdef0123456789abcdef0123456789abcdef0123456789abcde"

            # addresses/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"

    # allow use of the RESUME extension over plaintext connections:

    # do not enable this unless the ircd is only accessible over internal networks

    allow-plaintext-resume: 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

    # 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 long to ban offenders for. after banning them, the number of connections is

        # reset, which lets you use /UNDLINE to unban people

        throttle-ban-duration: 10m

        # 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. note that CIDR

        # widths defined here override the default CIDR width --- the limit

        # will apply to the entire CIDR no matter how large or small it is

        custom-limits:

            # "8.8.0.0/16":

            #     max-concurrent-connections: 128

            #     max-connections-per-window: 1024

    # 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.ergo. 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.

    ip-cloaking:

        # whether to enable IP cloaking

        enabled: true

        # fake TLD at the end of the hostname, e.g., pwbs2ui4377257x8.irc

        # you may want to use your network name here

        netname: "usr.{{ergo_network_name}}"

        # 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"

    # 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: "/var/ergo"

# 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

        # 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

        bcrypt-cost: 9

        # length of time a user has to verify their account before it can be re-registered

        verify-timeout: "32h"

        # callbacks to allow

        enabled-callbacks:

            - none # no verification needed, will instantly register successfully

        # example configuration for sending verification emails

        # callbacks:

        #     mailto:

        #         sender: "[email protected]"

        #         require-tls: true

        #         helo-domain: "my.network" # defaults to server name if unset

        #         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"

        #         blacklist-regexes:

        #         #    - ".*@mailinator.com"

    # 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 sometimes useful for compatibility with old clients that don't support SASL

    login-via-pass-command: false

    # 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

        enabled: true

        # 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?

        additional-nick-limit: 2

        # method describes how nickname reservation is handled

        #   timeout:  let the user change to the registered nickname, give them X seconds

        #             to login and then rename them if they haven't done so

        #   strict:   don't let the user change to the registered nickname unless they're

        #             already logged-in using SASL or NickServ

        #   optional: no enforcement by default, but allow users to opt in to

        #             the enforcement level of their choice

        #

        # 'optional' matches the behavior of other NickServs, but 'strict' is

        # preferable if all your users can enable SASL.

        method: strict

        # allow users to set their own nickname enforcement status, e.g.,

        # to opt out of strict enforcement

        allow-custom-enforcement: false

        # rename-timeout - this is how long users have 'til they're renamed

        rename-timeout: 30s

        # 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 enforce-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: {{ergo_force_nick_equals_account}}

    # 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"

    # 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.\-_/]+$'

        # options controlling users requesting vhosts:

        user-requests: