aboutsummaryrefslogblamecommitdiffstats
path: root/terminaldweller.com/ircd/ircd.yaml
blob: 987f0bbe2e2527e3bc8a852fc61682f29990c2d0 (plain) (tree)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010

















































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































































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

# server configuration
server:
    # server name
    name: irc.terminaldweller.com

    # 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: /etc/letsencrypt/live/irc.terminaldweller.com/fullchain.pem
                key: /etc/letsencrypt/live/irc.terminaldweller.com/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.3

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

        # 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,
    # and 'permissive', which allows identifiers containing unusual characters like
    # emoji, at the cost of increased vulnerability to homoglyph attacks and potential
    # client compatibility problems. 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: "" #pragma: allowlist secret

    # 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

    # 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" #pragma: allowlist secret

            # password the gateway uses to connect, made with `ergo genpasswd`
            password: "" # pragma: allowlist secret

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

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

    # 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

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

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

        # 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
            # 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: "" # pragma: allowlist secret
            #     implicit-tls: false # TLS from the first byte, typically on port 465
            blacklist-regexes:
            #    - ".*@mailinator.com"
            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: 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?
        # (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 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: 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: []
        # 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

# 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

# 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

# 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: "" # pragma: allowlist secret

        # 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: "5e3bd8ab6f8c6f6a614d4b2245fd6b5737a6e59917c6719de62b55bac77b978c" # pragma: allowlist secret
        # 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: "" #pragma: allowlist secret

# 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 exclusing 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 datastore
    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: "" # pragma: allowlist secret
        history-database: "ergo_history"
        timeout: 3s
        max-conns: 4
        # this may be necessary to prevent middleware from closing your connections:
        #conn-max-lifetime: 180s

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

    # 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

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

    # 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

# 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

# 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
    # # you can configure tokens to be signed either with HMAC and a symmetric secret:
    # secret: "65PHvk0K1_sM-raTsCEhatVkER_QD8a0zVV8gG2EWcI"
    # # or with an RSA private key:
    # #rsa-private-key-file: "extjwt.pem"

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

# 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

    # how many channel-specific events (messages, joins, parts) should be tracked per channel?
    channel-length: 2048

    # how many direct messages and notices should be tracked per user?
    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 (currently only MySQL).
    # in order to enable any of this functionality, you must configure a MySQL server
    # in the `datastore.mysql` section. 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?
        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