doc/oper-guide/config.rst

   1 Server config file format
   2 =========================
   3
   4 General format
   5 ~~~~~~~~~~~~~~
   6
   7 The config file consists of a series of BIND-style blocks. Each block
   8 consists of a series of values inside it which pertain to configuration
   9 settings that apply to the given block.
  10
  11 Several values take lists of values and have defaults preset inside
  12 them. Prefix a keyword with a tilde (``~``) to override the default and
  13 disable it.
  14
  15 A line may also be a .include directive, which is of the form::
  16
  17   .include "file"
  18
  19 and causes file to be read in at that point, before the rest of
  20 the current file is processed. Relative paths are first tried relative
  21 to ``PREFIX`` and then relative to ``ETCPATH`` (normally ``PREFIX``/etc).
  22
  23 Anything from a ``#`` to the end of a line is a comment. Blank lines are
  24 ignored. C-style comments are also supported.
  25
  26 Specific blocks and directives
  27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  28
  29 Not all configuration blocks and directives are listed here, only the
  30 most common ones. More blocks and directives will be documented in later
  31 revisions of this manual.
  32
  33 loadmodule directive
  34 --------------------
  35
  36 ::
  37
  38    loadmodule "text";
  39
  40 Loads a module into the IRCd. In charybdis 1.1, most modules are
  41 automatically loaded in. In future versions, it is intended to remove
  42 this behaviour as to allow for easy customization of the IRCd's
  43 featureset.
  44
  45 serverinfo {} block
  46 -------------------
  47
  48 ::
  49
  50    serverinfo {
  51         name = "text";
  52         sid = "text";
  53         description = "text";
  54         network_name = "text";
  55         network_desc = "text";
  56         hub = boolean;
  57         vhost = "text";
  58         vhost6 = "text";
  59    };
  60
  61 The serverinfo {} block defines the core operational parameters of the
  62 IRC server.
  63
  64 **serverinfo {} variables**
  65
  66 name
  67     The name of the IRC server that you are configuring. This must
  68     contain at least one dot. It is not necessarily equal to any DNS
  69     name. This must be unique on the IRC network.
  70
  71 sid
  72     A unique ID which describes the server. This consists of one digit
  73     and two characters which can be digits or letters.
  74
  75 description
  76     A user-defined field of text which describes the IRC server. This
  77     information is used in ``/links`` and ``/whois`` requests. Geographical
  78     location information could be a useful use of this field, but most
  79     administrators put a witty saying inside it instead.
  80
  81 network\_name
  82     The name of the IRC network that this server will be a member of.
  83     This is used in the welcome message and ``NETWORK=`` in 005.
  84
  85 hub
  86     A boolean which defines whether or not this IRC server will be
  87     serving as a hub, i.e. have multiple servers connected to it.
  88
  89 vhost
  90     An optional text field which defines an IPv4 address from which
  91     to connect outward to other IRC servers.
  92
  93 vhost6
  94     An optional text field which defines an IPv6 address from which
  95     to connect outward to other IRC servers.
  96
  97 admin {} block
  98 --------------
  99
 100 ::
 101
 102    admin {
 103        name = "text";
 104            description = "text";
 105            email = "text";
 106    };
 107
 108 This block provides the information which is returned by the ``ADMIN``
 109 command.
 110
 111 name
 112     The name of the administrator running this service.
 113
 114 description
 115     The description of the administrator's position in the network.
 116
 117 email
 118     A point of contact for the administrator, usually an e-mail address.
 119
 120 class {} block
 121 --------------
 122
 123 ::
 124
 125     class "name" {
 126             ping_time = duration;
 127             number_per_ident = number;
 128             number_per_ip = number;
 129             number_per_ip_global = number;
 130             cidr_ipv4_bitlen = number;
 131             cidr_ipv6_bitlen = number;
 132             number_per_cidr = number;
 133             max_number = number;
 134             sendq = size;
 135     };
 136
 137     class "name" {
 138             ping_time = duration;
 139             connectfreq = duration;
 140             max_number = number;
 141             sendq = size;
 142     };
 143
 144 Class blocks define classes of connections for later use. The class name
 145 is used to connect them to other blocks in the config file (auth{} and
 146 connect{}). They must be defined before they are used.
 147
 148 Classes are used both for client and server connections, but most
 149 variables are different.
 150
 151 **class {} variables: client classes**
 152
 153 ping\_time
 154     The amount of time between checking pings for clients, e.g.: 2
 155     minutes
 156
 157 number\_per\_ident
 158     The amount of clients which may be connected from a single identd
 159     username on a per-IP basis, globally. Unidented clients all count as
 160     the same username.
 161
 162 number\_per\_ip
 163     The amount of clients which may be connected from a single IP
 164     address.
 165
 166 number\_per\_ip\_global
 167     The amount of clients which may be connected globally from a single
 168     IP address.
 169
 170 cidr\_ipv4\_bitlen
 171     The netblock length to use with CIDR-based client limiting for IPv4
 172     users in this class (between 0 and 32).
 173
 174 cidr\_ipv6\_bitlen
 175     The netblock length to use with CIDR-based client limiting for IPv6
 176     users in this class (between 0 and 128).
 177
 178 number\_per\_cidr
 179     The amount of clients which may be connected from a single netblock.
 180
 181     If this needs to differ between IPv4 and IPv6, make different
 182     classes for IPv4 and IPv6 users.
 183
 184 max\_number
 185     The maximum amount of clients which may use this class at any given
 186     time.
 187
 188 sendq
 189     The maximum size of the queue of data to be sent to a client before
 190     it is dropped.
 191
 192 **class {} variables: server classes**
 193
 194 ping\_time
 195     The amount of time between checking pings for servers, e.g.: 2
 196     minutes
 197
 198 connectfreq
 199     The amount of time between autoconnects. This must at least be one
 200     minute, as autoconnects are evaluated with that granularity.
 201
 202 max\_number
 203     The amount of servers to autoconnect to in this class. More
 204     precisely, no autoconnects are done if the number of servers in this
 205     class is greater than or equal max\_number
 206
 207 sendq
 208     The maximum size of the queue of data to be sent to a server before
 209     it is dropped.
 210
 211 auth {} block
 212 -------------
 213
 214 ::
 215
 216     auth {
 217         user = "hostmask";
 218         password = "text";
 219         spoof = "text";
 220         flags = list;
 221         class = "text";
 222     };
 223
 224 auth {} blocks allow client connections to the server, and set various
 225 properties concerning those connections.
 226
 227 Auth blocks are evaluated from top to bottom in priority, so put special
 228 blocks first.
 229
 230 auth {} variables
 231 ~~~~~~~~~~~~~~~~~
 232
 233 user
 234     A hostmask (``user@host``) that the auth {} block applies to. It is
 235     matched against the hostname and IP address (using :: shortening for
 236     IPv6 and prepending a 0 if it starts with a colon) and can also use
 237     CIDR masks. You can have multiple user entries.
 238
 239 password
 240     An optional password to use for authenticating into this auth{}
 241     block. If the password is wrong the user will not be able to connect
 242     (will not fall back on another auth{} block).
 243
 244 spoof
 245     An optional fake hostname (or ``user@host``) to apply to users
 246     authenticated to this auth{} block. In ``STATS i`` and ``TESTLINE``, an
 247     equals sign (=) appears before the ``user@host`` and the spoof is shown.
 248
 249 flags
 250     A list of flags to apply to this ``auth{}`` block. They are listed
 251     below. Some of the flags appear as a special character,
 252     parenthesized in the list, before the ``user@host`` in ``STATS i`` and
 253     ``TESTLINE``.
 254
 255 class
 256     A name of a class to put users matching this auth{} block into.
 257
 258 auth {} flags
 259 ~~~~~~~~~~~~~
 260
 261 encrypted
 262     The password used has been encrypted.
 263
 264 spoof\_notice
 265     Causes the IRCd to send out a server notice when activating a spoof
 266     provided by this auth{} block.
 267
 268 exceed\_limit (>)
 269     Users in this auth{} block can exceed class-wide limitations.
 270
 271 dnsbl\_exempt ($)
 272     Users in this auth{} block are exempted from DNS blacklist checks.
 273     However, they will still be warned if they are listed.
 274
 275 kline\_exempt (^)
 276     Users in this auth{} block are exempted from DNS blacklists, k:lines
 277     and x:lines.
 278
 279 spambot\_exempt
 280     Users in this auth{} block are exempted from spambot checks.
 281
 282 shide\_exempt
 283     Users in this auth{} block are exempted from some serverhiding
 284     effects.
 285
 286 jupe\_exempt
 287     Users in this auth{} block do not trigger an alarm when joining
 288     juped channels.
 289
 290 resv\_exempt
 291     Users in this auth{} block may use reserved nicknames and channels.
 292
 293     .. note:: The initial nickname may still not be reserved.
 294
 295 flood\_exempt (\|) Users in this auth{} block may send arbitrary
 296     amounts of commands per time unit to the server. This does not
 297     exempt them from any other flood limits. You should use this
 298     setting with caution.
 299
 300 no\_tilde (-)
 301     Users in this auth{} block will not have a tilde added to their
 302     username if they do not run identd.
 303
 304 need\_ident (+)
 305     Users in this auth{} block must have identd, otherwise they will be
 306     rejected.
 307
 308 need\_ssl
 309     Users in this auth{} block must be connected via SSL/TLS, otherwise
 310     they will be rejected.
 311
 312 need\_sasl
 313     Users in this auth{} block must identify via SASL, otherwise they
 314     will be rejected.
 315
 316 exempt {} block
 317 ---------------
 318
 319 ::
 320
 321     exempt {
 322         ip = "ip";
 323     };
 324
 325 An exempt block specifies IP addresses which are exempt from ``D:lines`` and
 326 throttling. Multiple addresses can be specified in one block. Clients
 327 coming from these addresses can still be ``K/G/X:lined`` or banned by a DNS
 328 blacklist unless they also have appropriate flags in their auth{} block.
 329
 330 **exempt {} variables**
 331
 332 ip
 333     The IP address or CIDR range to exempt.
 334
 335 privset {} block
 336 ----------------
 337
 338 ::
 339
 340     privset {
 341         extends = "name";
 342         privs = list;
 343     };
 344
 345 A privset (privilege set) block specifies a set of operator privileges.
 346
 347 **privset {} variables**
 348
 349 extends
 350     An optional privset to inherit. The new privset will have all
 351     privileges that the given privset has.
 352
 353 privs
 354     Privileges to grant to this privset. These are described in the
 355     operator privileges section.
 356
 357 operator {} block
 358 -----------------
 359
 360 ::
 361
 362    operator "name" {
 363         user = "hostmask";
 364         password = "text";
 365         rsa_public_key_file = "text";
 366         umodes = list;
 367         snomask = "text";
 368         flags = list;
 369    };
 370
 371 Operator blocks define who may use the ``OPER`` command to gain extended
 372 privileges.
 373
 374 **operator {} variables**
 375
 376 user
 377     A hostmask that users trying to use this operator {} block must
 378     match. This is checked against the original host and IP address;
 379     CIDR is also supported. So auth {} spoofs work in operator {}
 380     blocks; the real host behind them is not checked. Other kind of
 381     spoofs do not work in operator {} blocks; the real host behind them
 382     is checked.
 383
 384     Note that this is different from charybdis 1.x where all kinds of
 385     spoofs worked in operator {} blocks.
 386
 387 password
 388     A password used with the ``OPER`` command to use this operator {} block.
 389     Passwords are encrypted by default, but may be unencrypted if
 390     ~encrypted is present in the flags list.
 391
 392 rsa\_public\_key\_file
 393     An optional path to a RSA public key file associated with the
 394     operator {} block. This information is used by the ``CHALLENGE``
 395     command, which is an alternative authentication scheme to the
 396     traditional ``OPER`` command.
 397
 398 umodes
 399     A list of usermodes to apply to successfully opered clients.
 400
 401 snomask
 402     An snomask to apply to successfully opered clients.
 403
 404 privset
 405     The privilege set granted to successfully opered clients. This must
 406     be defined before this operator{} block.
 407
 408 flags
 409     A list of flags to apply to this operator{} block. They are listed
 410     below.
 411
 412 **operator {} flags**
 413
 414 encrypted
 415     The password used has been encrypted. This is enabled by default,
 416     use ~encrypted to disable it.
 417
 418 need\_ssl
 419     Restricts use of this operator{} block to SSL/TLS connections only.
 420
 421 connect {} block
 422 ----------------
 423
 424 ::
 425
 426     connect "name" {
 427         host = "text";
 428         send_password = "text";
 429         accept_password = "text";
 430         port = number;
 431         hub_mask = "mask";
 432         leaf_mask = "mask";
 433         class = "text";
 434         flags = list;
 435         aftype = protocol;
 436     };
 437
 438 Connect blocks define what servers may connect or be connected to.
 439
 440 **connect {} variables**
 441
 442 host
 443     The hostname or IP to connect to.
 444
 445     .. note:: Furthermore, if a hostname is used, it must have an
 446               ``A`` or ``AAAA`` record (no ``CNAME``) and it must be
 447               the primary hostname for inbound connections to work.
 448
 449 send\_password
 450     The password to send to the other server.
 451
 452 accept\_password
 453     The password that should be accepted from the other server.
 454
 455 port
 456     The port on the other server to connect to.
 457
 458 hub\_mask
 459     An optional domain mask of servers allowed to be introduced by this
 460     link. Usually, "\*" is fine. Multiple hub\_masks may be specified,
 461     and any of them may be introduced. Violation of hub\_mask and
 462     leaf\_mask restrictions will cause the local link to be closed.
 463
 464 leaf\_mask
 465     An optional domain mask of servers not allowed to be introduced by
 466     this link. Multiple leaf\_masks may be specified, and none of them
 467     may be introduced. leaf\_mask has priority over hub\_mask.
 468
 469 class
 470     The name of the class this server should be placed into.
 471
 472 flags
 473     A list of flags concerning the connect block. They are listed below.
 474
 475 aftype
 476     The protocol that should be used to connect with, either ipv4 or
 477     ipv6. This defaults to neither, allowing connection using either
 478     address family.
 479
 480 **connect {} flags**
 481
 482 encrypted
 483     The value for accept\_password has been encrypted.
 484
 485 autoconn
 486     The server should automatically try to connect to the server defined
 487     in this connect {} block if it's not connected already and
 488     max\_number in the class is not reached yet.
 489
 490 compressed
 491     Ziplinks should be used with this server connection. This compresses
 492     traffic using zlib, saving some bandwidth and speeding up netbursts.
 493
 494     If you have trouble setting up a link, you should turn this off as
 495     it often hides error messages.
 496
 497 topicburst
 498     Topics should be bursted to this server.
 499
 500     This is enabled by default.
 501
 502 listen {} block
 503 ---------------
 504
 505 ::
 506
 507    listen {
 508         host = "text";
 509         port = number;
 510    };
 511
 512 A listen block specifies what ports a server should listen on.
 513
 514 **listen {} variables**
 515
 516 host
 517     An optional host to bind to. Otherwise, the ircd will listen on all
 518     available hosts.
 519
 520 port
 521     A port to listen on. You can specify multiple ports via commas, and
 522     define a range by seperating the start and end ports with two dots
 523     (..).
 524
 525 modules {} block
 526 ----------------
 527
 528 ::
 529
 530     modules {
 531         path = "text";
 532         module = text;
 533     };
 534
 535 The modules block specifies information for loadable modules.
 536
 537 **modules {} variables**
 538
 539 path
 540     Specifies a path to search for loadable modules.
 541
 542 module
 543     Specifies a module to load, similar to loadmodule.
 544
 545 general {} block
 546 ----------------
 547
 548 ::
 549
 550     modules {
 551         values
 552     };
 553
 554 The general block specifies a variety of options, many of which were in
 555 ``config.h`` in older daemons. The options are documented in
 556 ``reference.conf``.
 557
 558 channel {} block
 559 ----------------
 560
 561 ::
 562
 563     modules {
 564         values
 565     };
 566
 567 The channel block specifies a variety of channel-related options, many
 568 of which were in ``config.h`` in older daemons. The options are
 569 documented in ``reference.conf``.
 570
 571 serverhide {} block
 572 -------------------
 573
 574 ::
 575
 576     modules {
 577         values
 578     };
 579
 580 The serverhide block specifies options related to server hiding. The
 581 options are documented in ``reference.conf``.
 582
 583 blacklist {} block
 584 ------------------
 585
 586 ::
 587
 588     blacklist {
 589         host = "text";
 590         reject_reason = "text";
 591     };
 592
 593 The blacklist block specifies DNS blacklists to check. Listed clients
 594 will not be allowed to connect. IPv6 clients are not checked against
 595 these.
 596
 597 Multiple blacklists can be specified, in pairs with first host then
 598 reject\_reason.
 599
 600 **blacklist {} variables**
 601
 602 host
 603     The DNSBL to use.
 604
 605 reject\_reason
 606     The reason to send to listed clients when disconnecting them.
 607
 608 alias {} block
 609 --------------
 610
 611 ::
 612
 613     alias "name" {
 614         target = "text";
 615     };
 616
 617 Alias blocks allow the definition of custom commands. These commands
 618 send ``PRIVMSG`` to the given target. A real command takes precedence above
 619 an alias.
 620
 621 **alias {} variables**
 622
 623 target
 624     The target nick (must be a network service (umode ``+S``)) or
 625     user@server. In the latter case, the server cannot be this server,
 626     only opers can use user starting with "opers" reliably and the user
 627     is interpreted on the target server only so you may need to use
 628     nick@server instead).
 629
 630 cluster {} block
 631 ----------------
 632
 633 ::
 634
 635     cluster {
 636         name = "text";
 637         flags = list;
 638     };
 639
 640 The cluster block specifies servers we propagate things to
 641 automatically. This does not allow them to set bans, you need a separate
 642 shared{} block for that.
 643
 644 Having overlapping cluster{} items will cause the command to be executed
 645 twice on the target servers. This is particularly undesirable for ban
 646 removals.
 647
 648 The letters in parentheses denote the flags in ``/stats`` U.
 649
 650 **cluster {} variables**
 651
 652 name
 653     The server name to share with, this may contain wildcards and may be
 654     stacked.
 655
 656 flags
 657     The list of what to share, all the name lines above this (up to
 658     another flags entry) will receive these flags. They are listed
 659     below.
 660
 661 **cluster {} flags**
 662
 663 kline (K)
 664     Permanent ``K:lines``
 665
 666 tkline (k)
 667     Temporary ``K:lines``
 668
 669 unkline (U)
 670     ``K:line`` removals
 671
 672 xline (X)
 673     Permanent ``X:lines``
 674
 675 txline (x)
 676     Temporary ``X:lines``
 677
 678 unxline (Y)
 679     ``X:line`` removals
 680
 681 resv (Q)
 682     Permanently reserved nicks/channels
 683
 684 tresv (q)
 685     Temporarily reserved nicks/channels
 686
 687 unresv (R)
 688     ``RESV`` removals
 689
 690 locops (L)
 691     ``LOCOPS`` messages (sharing this with \* makes ``LOCOPS`` rather similar to
 692     ``OPERWALL`` which is not useful)
 693
 694 all
 695     All of the above
 696
 697 shared {} block
 698 ---------------
 699
 700 ::
 701
 702     shared {
 703         oper = "user@host", "server";
 704         flags = list;
 705     };
 706
 707 The shared block specifies opers allowed to perform certain actions on
 708 our server remotely. These are ordered top down. The first one matching
 709 will determine the oper's access. If access is denied, the command will
 710 be silently ignored.
 711
 712 The letters in parentheses denote the flags in ``/stats U``.
 713
 714 **shared {} variables**
 715
 716 oper
 717     The user@host the oper must have, and the server they must be on.
 718     This may contain wildcards.
 719
 720 flags
 721     The list of what to allow, all the oper lines above this (up to
 722     another flags entry) will receive these flags. They are listed
 723     below.
 724
 725     .. note:: While they have the same names, the flags have subtly
 726               different meanings from those in the cluster{} block.
 727
 728 **shared {} flags**
 729
 730 kline (K)
 731     Permanent and temporary ``K:lines``
 732
 733 tkline (k)
 734     Temporary ``K:lines``
 735
 736 unkline (U)
 737     ``K:line`` removals
 738
 739 xline (X)
 740     Permanent and temporary ``X:lines``
 741
 742 txline (x)
 743     Temporary ``X:lines``
 744
 745 unxline (Y)
 746     ``X:line`` removals
 747
 748 resv (Q)
 749     Permanently and temporarily reserved nicks/channels
 750
 751 tresv (q)
 752     Temporarily reserved nicks/channels
 753
 754 unresv (R)
 755     ``RESV`` removals
 756
 757 all
 758     All of the above; this does not include locops, rehash, dline,
 759     tdline or undline.
 760
 761 locops (L)
 762     ``LOCOPS`` messages (accepting this from \* makes ``LOCOPS`` rather similar
 763     to ``OPERWALL`` which is not useful); unlike the other flags, this can
 764     only be accepted from \*@\* although it can be restricted based on
 765     source server.
 766
 767 rehash (H)
 768     ``REHASH`` commands; all options can be used
 769
 770 dline (D)
 771     Permanent and temporary ``D:lines``
 772
 773 tdline (d)
 774     Temporary ``D:lines``
 775
 776 undline (E)
 777     ``D:line`` removals
 778
 779 none
 780     Allow nothing to be done
 781
 782 service {} block
 783 ----------------
 784
 785 ::
 786
 787     service {
 788         name = "text";
 789     };
 790
 791 The service block specifies privileged servers (services). These servers
 792 have extra privileges such as setting login names on users and
 793 introducing clients with umode ``+S`` (unkickable, hide channels, etc). This
 794 does not allow them to set bans, you need a separate shared{} block for
 795 that.
 796
 797 Do not place normal servers here.
 798
 799 Multiple names may be specified but there may be only one service{}
 800 block.
 801
 802 **service {} variables**
 803
 804 name
 805     The server name to grant special privileges. This may not contain
 806     wildcards.
 807
 808 Hostname resolution (DNS)
 809 ~~~~~~~~~~~~~~~~~~~~~~~~~
 810
 811 Charybdis uses solely DNS for all hostname/address lookups (no
 812 ``/etc/hosts`` or anything else). The DNS servers are taken from
 813 ``/etc/resolv.conf``. If this file does not exist or no valid IP
 814 addresses are listed in it, the local host (``127.0.0.1``) is used. (Note
 815 that the latter part did not work in older versions of Charybdis.)
 816
 817 IPv4 as well as IPv6 DNS servers are supported, but it is not possible
 818 to use both IPv4 and IPv6 in ``/etc/resolv.conf``.
 819
 820 For both security and performance reasons, it is recommended that a
 821 caching nameserver such as BIND be run on the same machine as Charybdis
 822 and that ``/etc/resolv.conf`` only list ``127.0.0.1``.