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