doc/oper-guide/config.rst

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